diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index da848f8f..b768f0e8 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -26,4 +26,4 @@ A clear and concise description of what you want to happen. A clear and concise description of any alternative solutions or features you've considered. ### Additional context -Add any other context or screenshots about the feature request here. +Add any other context, such as the desired tmsh configuration, about the feature request here. diff --git a/.github/workflows/autoclose.yml b/.github/workflows/autoclose.yml new file mode 100644 index 00000000..bf4d285c --- /dev/null +++ b/.github/workflows/autoclose.yml @@ -0,0 +1,20 @@ +name: No Response + +# Both `issue_comment` and `scheduled` event types are required for this Action +# to work properly. +on: + issue_comment: + types: [created] + schedule: + # Schedule for five minutes after the hour, every hour + - cron: '5 * * * *' + +jobs: + noResponse: + runs-on: ubuntu-latest + steps: + - uses: lee-dohm/no-response@v0.5.0 + with: + token: ${{ github.token }} + daysUntilClose: 30 + responseRequiredLabel: question diff --git a/.gitignore b/.gitignore index 055537a0..7143f2e3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,18 @@ .vscode +jsconfig.json +*.tfstate* .nyc_output/ out/ node_modules/ -build/ +/build/ docs/_build/ coverage/ npm-debug.log docs/schema-reference.rst docs/do.schema.json dist/ +test/env/terraform/plans/openstack/.terraform* test/logs test_harness.json +harness_facts.json *.swp diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index bb490d68..44d2ed6d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,256 +1,235 @@ -image: node:12 +image: $DOCKER_URL/node:12-buster stages: + - update + - atg-shared-checks - lint - test + - apidocs - build - docs - deploy - integration-test - teardown - - post build - - publish variables: - PROJECT_NAME: ${BIGIP_VERSION} - PROJECT_DIR: /root/deploy-projects/${CI_PROJECT_NAME} - NUMBER_OF_BIGIP: 3 - DO_LICENSING: 'false' - DO_PROVISIONING: 'false' - DO_PHONING_HOME: 'false' - TEST_HARNESS_FILE: ${CI_PROJECT_DIR}/harness_facts_flat_${BIGIP_VERSION}.json - BIGIP_VERSION: ${DEFAULT_BIGIP_VERSION} - BIGIP_BUILD: ${DEFAULT_BIGIP_BUILD} + TEST_HARNESS_FILE: ${CI_PROJECT_DIR}/harness_facts.json + ESR_PRODUCT: DO + ESR_TEST_RUN_ID: ${CI_JOB_ID} + ESR_TEST_RUN_WEB_URL: ${CI_JOB_URL} + TEST_REPORTER_OPTIONS: "--reporter mocha-multi-reporters --reporter-options configFile=test/mochaReporterConfig.json" + TF_DIRECTORY: test/env/terraform + TF_HTTP_LOCK_METHOD: POST + TF_HTTP_UNLOCK_METHOD: DELETE + TF_HTTP_USERNAME: ${CI_REGISTRY_USER} + TF_HTTP_PASSWORD: ${CI_JOB_TOKEN} + TF_CLI_ARGS_apply: "-auto-approve" + TF_CLI_ARGS_destroy: "-auto-approve" + TF_STATE_URL: "$CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state" + # terraform will try to update state 5(4+1) times every 3 minutes. + TF_HTTP_RETRY_MAX: 4 + TF_HTTP_RETRY_WAIT_MIN: 3 + DOCS_BUILD_DIR: "docs/_build/html" + +# This inherits all the jobs defined in the parent template +# Override variables in this project as needed +include: +# adds atg-shared-checks stage and jobs +# adds atg_shared_checks_result job to test stage + - project: automation-toolchain/atg-shared-templates + file: security/base.gitlab-ci.yml + +update_autotool_deps: + stage: update + rules: + - if: '$UPDATE_DEPS =~ /true/i' + needs: [] + image: $DOCKER_URL/node:14 + variables: + UPDATE_BRANCH_NAME: update_autotool_deps + script: + - . ./scripts/dev/update-do-deps.sh + - > + if [ "$AUTOTOOL_DIFF" = "true" ]; then + git push -f origin ${UPDATE_BRANCH_NAME} + node ./scripts/dev/createMR.js + fi + tags: [cm-official-docker-executor] lint: stage: lint + needs: [] tags: - cm-official-docker-executor script: - - npm ci + - npm ci --no-optional - npm run lint test_node:4: - image: node:4 + image: $DOCKER_URL/node:4 stage: test + needs: [] tags: - - do-test-docker-executor + - cm-official-docker-executor script: - npm install --global npm@5.10.0 - - npm install + - npm install --no-optional - npm install mocha@5.2.0 - npm test test_node:6: - image: node:6 + image: $DOCKER_URL/node:6 stage: test + needs: [] tags: - - do-test-docker-executor + - cm-official-docker-executor script: - - npm install + - npm install --no-optional - npm install mocha@6.2.2 - - npm test + - npm test -- $TEST_REPORTER_OPTIONS + artifacts: + when: always + reports: + junit: test_report.xml test_node:8: - image: node:8 + image: $DOCKER_URL/node:8 stage: test + needs: [] tags: - - do-test-docker-executor + - cm-official-docker-executor script: - npm ci - npm install mocha@7 - - npm test + - npm test -- $TEST_REPORTER_OPTIONS + artifacts: + when: always + reports: + junit: test_report.xml test_node:latest: stage: test - tags: - - do-test-docker-executor - script: - - npm ci - - npm test - -# the following variables should be defined for deploy, integration-tests and teardown: -# CICD_AUTH_OS_USERNAME - VIO user -# CICD_AUTH_OS_PASSWORD - VIO password -# CICD_AUTH_OS_PROJECT - VIO project -# BIGIP_VERSION - BIG-IP Version (ex: 13.1.1.4) -# BIGIP_BUILD - BIG-IP Build (ex: 0.0.4) -deploy: - image: ${CICD_CONTAINER_DEPLOY_ARTIFACTORY} + needs: [] tags: - cm-official-docker-executor - only: - - schedules - - tags - - triggers - stage: deploy - variables: - DEFAULT_RETRY_DELAY: 20 - DEFAULT_RETRIES: 60 - DEVICE_ANSIBLE_CONNECTION_DELAY: 10 - DEVICE_ANSIBLE_CONNECTION_RETRIES: 100 - DEVICE_FAILOVER_LINKSUP_DELAY: 10 - DEVICE_HTTPS_PORT_DELAY: 10 - SSH_AVAILABILITY_DELAY: 10 - SSH_AVAILABILITY_RETRIES: 100 - VIO_DEPLOYMENT_DELAY: 20 - VIO_DEPLOYMENT_RETRIES: 100 script: - - export RPM_PACKAGE=$(ls ${CI_PROJECT_DIR}/dist/*.rpm) - - cd /root/cicd-bigip-deploy && make configure && make printvars - - ls -als "${PROJECT_DIR}" - - cat "${PROJECT_DIR}/project-declaration-parsed" - - make setup - - cp ${PROJECT_DIR}/harness_facts_flat.json ${TEST_HARNESS_FILE} - - cd ${CI_PROJECT_DIR} - - if [[ $? != 0 ]]; then echo setup failed && exit 1; fi - - curl -sL https://rpm.nodesource.com/setup_12.x | bash - - - yum install -y nodejs - - npm install - - node test/integration/setup.js - artifacts: - name: ${CI_COMMIT_REF_NAME}_bigip_${BIGIP_BRANCH}.${BIGIP_VERSION}.${BIGIP_BUILD}_harness_info - paths: - - ${TEST_HARNESS_FILE} - expire_in: 1 day - -integration-test: - tags: - - cm-official-docker-executor - only: - - schedules - - tags - - triggers - stage: integration-test - script: - - npm install - - echo BIGIP_VERSION $BIGIP_VERSION - - npm run integration - after_script: - - apt-get update - - apt-get install -y jq - - apt-get install -y expect - - scripts/dev/collectRemoteIntegrationTestLogs.sh ${TEST_HARNESS_FILE} + - npm ci + - npm test -- $TEST_REPORTER_OPTIONS artifacts: - name: f5-declarative-onboarding-$CI_BUILD_REF when: always - paths: - - test/logs + reports: + junit: test_report.xml -teardown: - image: ${CICD_CONTAINER_DEPLOY_ARTIFACTORY} - tags: - - cm-official-docker-executor - script: - - cd /root/cicd-bigip-deploy && make configure && make teardown - when: always - only: - - schedules - - tags - - triggers - stage: teardown +test-bigiq-ui: + stage: test + needs: [] + parallel: + matrix: + - BIGIQ_BRANCH: [master/palisade, master/quartz, master/rainier] + allow_failure: true + script: + - git clone --branch $BIGIQ_BRANCH --depth 1 https://gitlab-ci-token:${CI_JOB_TOKEN}@$CI_SERVER_HOST:$CI_SERVER_PORT/bigiq-mgmt/bigiq-mgmt-test + - cd bigiq-mgmt-test/tools/declarativeOnboardSchemaValidator + - npm ci + - cp -r ../../../src/schema/latest/ schema + - node validateDO_UiSchemaTest.js > output + - cat output + - 'grep -q "Total Failures : 0" output' -build rpm: - image: f5devcentral/containthedocs:rpmbuild +coverage: + image: $DOCKER_URL/node:16 + stage: test + needs: [] + tags: + - cm-official-docker-executor + script: + - PUBLIC_DIR='./public' + - mkdir -p ${PUBLIC_DIR} + - COVERAGE_DOCS=${PUBLIC_DIR}/coverage-docs + - mkdir -p ${COVERAGE_DOCS} + ## place code coverage docs under: /coverage-docs ## + - npm ci + - npm run coverage + - cp -R coverage/* ${COVERAGE_DOCS} + except: + # For develop, coverage is run in the pages job + - develop + - pipelines + artifacts: + paths: + - public + coverage: /All files[^|]*\|[^|]*\s+([\d\.]+)/ + +audit: + image: $DOCKER_URL/node:16 + needs: [] + stage: test + allow_failure: true + tags: + - cm-official-docker-executor + script: + - npm audit + +build_rpm: + image: $DOCKER_URL/node:14 stage: build + needs: [] tags: - cm-official-docker-executor + except: + - pipelines script: # setup node environment - - npm install --global npm@5.10.0 + - apt-get update && apt-get install -y rpm --no-install-recommends - scripts/build/buildRpm.sh + # ensure latest copyrights, requires dev dependencies + - npm ci --no-optional + - node node_modules/@f5devcentral/atg-shared-utilities-dev/scripts/dev/write-copyright.js -c -p scripts/dev/copyright.txt artifacts: name: ${CI_PROJECT_NAME}-${CI_JOB_NAME}-${CI_PIPELINE_IID} paths: - dist/ expire_in: 1 week -build asg: - image: docker:latest - stage: post build - except: - - schedules - tags: - - cm-official-docker-executor - dependencies: - - build rpm - script: - - IMAGE_NAME=f5-do-container - - ORGANIZATION_NAME=f5devcentral - - TARGET=$(ls dist/*.rpm) - # TAG is VERSION-RELEASE. Use awk to remove everything else - - IMAGE_TAG=$(echo $(basename $TARGET) | awk -F- -v PROJECT_NAME=${CI_PROJECT_NAME}- '{sub(PROJECT_NAME, ""); sub(".noarch.rpm", ""); print}') - - if [[ ${CI_COMMIT_REF_NAME} == 'master' ]]; then - - IMAGE_TAG=$(echo $IMAGE_TAG | grep -o "^[^-]\+") - - elif [[ ${CI_COMMIT_REF_NAME} != 'develop' ]]; then - - IMAGE_TAG=$CI_COMMIT_REF_NAME - - fi - - echo ${TARGET} ${IMAGE_TAG} - - docker build -f scripts/build/Dockerfile.asg -t ${ORGANIZATION_NAME}/${IMAGE_NAME}:${IMAGE_TAG} --build-arg TARGET=$TARGET . - - docker save ${ORGANIZATION_NAME}/${IMAGE_NAME}:${IMAGE_TAG} | gzip -c > dist/${ORGANIZATION_NAME}-${IMAGE_NAME}-${IMAGE_TAG}.tar.gz - artifacts: - name: ${CI_PROJECT_NAME}-${CI_JOB_NAME}-${CI_PIPELINE_IID} - paths: - - dist/ - expire_in: 1 week - -create postman collection: - stage: post build - except: - - schedules - tags: - - cm-official-docker-executor +reactivate_big_iq_license: + stage: build + needs: [] + rules: + - if: '$REACTIVATE_BIG_IQ_LICENSE =~ /true/i' script: - - node scripts/build/generatePostmanCollection.js - artifacts: - name: ${CI_PROJECT_NAME}-${CI_JOB_NAME}-${CI_PIPELINE_IID} - paths: - - dist/ - expire_in: 1 week + - npm ci + - node scripts/dev/reactivateBigIq.js -publish to artifactory: - stage: publish - only: - - tags - tags: - - cm-official-docker-executor - script: - - RPM_FILE=$(ls dist/*.rpm) - - RPM_NAME=$(basename $RPM_FILE) - - HASH_FILE=${RPM_FILE}.sha256 - - HASH_NAME=$(basename $HASH_FILE).txt - - POSTMAN_FILE=$(ls dist/*.collection.json) - - POSTMAN_NAME=$(basename $POSTMAN_FILE) - - >- - UPLOAD_RESULT=$(curl -H "Authorization: Bearer ${ARTIFACTORY_BEARER_TOKEN}" -X PUT --data-binary @${RPM_FILE} - ${ARTIFACTORY_BASE_URL}/f5-declarative-onboarding-rpm/${RPM_NAME}) - - echo $UPLOAD_RESULT - - if [[ "$UPLOAD_RESULT" == *errors* ]]; then echo error during RPM upload; exit 1; fi - - >- - UPLOAD_RESULT=$(curl -H "Authorization: Bearer ${ARTIFACTORY_BEARER_TOKEN}" -X PUT --data-binary @${HASH_FILE} - ${ARTIFACTORY_BASE_URL}/f5-declarative-onboarding-rpm/${HASH_NAME}) - - echo $UPLOAD_RESULT - - if [[ "$UPLOAD_RESULT" == *errors* ]]; then echo error during hash upload; exit 1; fi - - >- - UPLOAD_RESULT=$(curl -H "Authorization: Bearer ${ARTIFACTORY_BEARER_TOKEN}" -X PUT --data-binary @${POSTMAN_FILE} - ${ARTIFACTORY_BASE_URL}/f5-declarative-onboarding-rpm/${POSTMAN_NAME}) - - echo $UPLOAD_RESULT - - if [[ "$UPLOAD_RESULT" == *errors* ]]; then echo error during collection upload; exit 1; fi +build_api_docs: + image: $DOCKER_URL/node:12 + stage: apidocs + needs: [] + script: + # install packages + - npm install + # generate docs + - npm run make-api-docs + - mkdir apidocs && mv redoc-static.html apidocs/index.html + tags: + - cm-official-docker-executor + artifacts: + name: docs + paths: + - apidocs -create docs: +create_docs: image: ${CONTAINTHEDOCS_IMAGE} stage: build - except: - - tags - - schedules + allow_failure: true + needs: + - build_api_docs script: - - node scripts/build/schema-build.js - - node scripts/build/schema-check.js - - node scripts/build/schema-to-rst.js - if [ "$CI_COMMIT_REF_NAME" = "docs-staging" ] || [ "$CI_COMMIT_REF_NAME" = "docs-latest" ]; then - rm -rf docs/_templates - fi - make html + - API_DOCS_INDEX=${DOCS_BUILD_DIR}/apidocs.html + - cp apidocs/index.html ${API_DOCS_INDEX} - echo "Checking grammar and style" # Runs the grammar check on everything except the /docs/drafts directory - vale --glob='*.rst' . @@ -264,21 +243,190 @@ create docs: paths: - docs/_build/html +.deploy_common: &deploy_common + image: $INTEGRATION_DEPLOY_IMAGE + tags: + - do-test-docker-executor + stage: deploy + timeout: 1 hour + script: + - apk update + # Need to add bash, because included sh doen't support arrays + # used in build_harness_file.sh script to get IP addresses. + - apk add bash npm build-base python3 cmake + - if [[ $PROPERTY_TEST == true ]]; then + - export TF_VAR_bigip_count=1 + - else + - export TF_VAR_bigip_count=3 + - unset BIGIP_LICENSE # Licensing will be handled by integration testing + - fi + - cd "$TF_ROOT" + - terraform init + # In case of testing failure, BIGIP will not be destroyed, + # so before run we need to clean leftovers from last night. + - terraform destroy + - terraform apply + - export BIGIPS_ADDRESSES=$(terraform output --json admin_ip | jq -rc .[]) + - export ADMIN_USERNAME=$(terraform output --json admin_username | jq -rc .) + - export ADMIN_PASSWORD=$(terraform output --json admin_password | jq -rc .) + - cd - + - scripts/dev/build_harness_file.sh > $TEST_HARNESS_FILE + - npm ci + - node test/integration/setup.js + artifacts: + when: always + paths: + - ${TEST_HARNESS_FILE} + expire_in: 1 day + retry: + max: 1 + when: script_failure + +deploy_for_this_project: + rules: + - if: '$RUN_INTEGRATION_TEST =~ /true/i' + variables: + TF_ROOT: '$TF_DIRECTORY/plans/openstack' + TF_VAR_bigip_image: "$BIGIP_IMAGE" + TF_VAR_nic_count: "$NIC_COUNT" + before_script: + - export TRIM_VERSION="$(echo $BIGIP_IMAGE | cut -d '-' -f 2 | tr '.' -)" + - if [[ $PROPERTY_TEST == true ]]; then + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION-property" + - else + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION" + - fi + - export TF_HTTP_LOCK_ADDRESS="$TF_HTTP_ADDRESS/lock" + - export TF_HTTP_UNLOCK_ADDRESS=$TF_HTTP_LOCK_ADDRESS + - echo using RPM from our pipeline + - export RPM_PACKAGE=$(ls ${CI_PROJECT_DIR}/dist/*.rpm) + <<: *deploy_common + needs: + - job: build_rpm + artifacts: true + +deploy_for_other_project: + rules: + - if: '$TRIGGER_INTEGRATION_TEST =~ /true/i' + variables: + TF_ROOT: "$TF_DIRECTORY/plans/openstack" + TF_VAR_bigip_image: "$BIGIP_IMAGE" + TF_VAR_nic_count: "$NIC_COUNT" + before_script: + - export TRIM_VERSION="$(echo $BIGIP_IMAGE | cut -d '-' -f 2 | tr '.' -)" + - if [[ $PROPERTY_TEST == true ]]; then + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION-property" + - else + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION" + - fi + - export TF_HTTP_LOCK_ADDRESS="$TF_HTTP_ADDRESS/lock" + - export TF_HTTP_UNLOCK_ADDRESS=$TF_HTTP_LOCK_ADDRESS + - echo using RPM from cross-project pipeline + - export RPM_PACKAGE=$(ls ${UPSTREAM_RPM_PATH}/*.rpm) + <<: *deploy_common + needs: + - project: "$UPSTREAM_PROJECT_PATH" + job: "$UPSTREAM_JOB" + ref: "$UPSTREAM_REF" + artifacts: true + +integration-test: + tags: + - do-test-docker-executor + rules: + - if: '$RUN_INTEGRATION_TEST =~ /true/i' + - if: '$TRIGGER_INTEGRATION_TEST =~ /true/i' + stage: integration-test + timeout: 3 hours + before_script: + - apt-get update + - apt-get install -y jq + - export ESR_TEST_TYPE=integration + - export ESR_PRODUCT_VERSION=$(node -e "console.log(require('./package.json').version)" | cut -d '-' -f1) + - export ESR_BIG_IP_VERSION=$(echo $BIGIP_IMAGE | cut -d '-' -f 2) + - export GIT_SSL_NO_VERIFY=1 + - echo BIGIP_VERSION $ESR_BIG_IP_VERSION + - npm install --no-optional + script: + - if [[ $PROPERTY_TEST == true ]]; then + - export DO_HOST=$(cat ${TEST_HARNESS_FILE} | jq -r '.[0].admin_ip') + - export DO_USERNAME=$(cat ${TEST_HARNESS_FILE} | jq -r '.[0].f5_rest_user.username') + - export DO_PASSWORD=$(cat ${TEST_HARNESS_FILE} | jq -r '.[0].f5_rest_user.password') + - npm run property -- $TEST_REPORTER_OPTIONS + - else + - npm run integration -- $TEST_REPORTER_OPTIONS + - fi + after_script: + - apt-get install -y expect + - scripts/dev/collectRemoteIntegrationTestLogs.sh ${TEST_HARNESS_FILE} + artifacts: + name: f5-declarative-onboarding-$CI_BUILD_REF + when: always + paths: + - test/logs + reports: + junit: test_report.xml + expire_in: 1 week + +.teardown_common: &teardown_common + image: $INTEGRATION_DEPLOY_IMAGE + tags: + - do-test-docker-executor + stage: teardown + before_script: + # terraform doesn't support '.' in backend address. + - export TRIM_VERSION="$(echo $BIGIP_IMAGE | cut -d '-' -f 2 | tr '.' -)" + - if [[ $PROPERTY_TEST == true ]]; then + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION-property" + - else + - export TF_HTTP_ADDRESS="$TF_STATE_URL/openstack-$TRIM_VERSION" + - fi + script: + - cd $TF_DIRECTORY/plans/openstack + - terraform init + - terraform destroy + retry: + max: 1 + when: script_failure + +teardown_for_this_project: + rules: + - if: '$SKIP_TEARDOWN =~ /true/i' + when: never + - if: '$RUN_INTEGRATION_TEST =~ /true/i' + when: always + - when: never + needs: + - job: deploy_for_this_project + - job: integration-test + <<: *teardown_common + +teardown_for_other_project: + rules: + - if: '$SKIP_TEARDOWN =~ /true/i' + when: never + - if: '$TRIGGER_INTEGRATION_TEST =~ /true/i' + when: always + - when: never + needs: + - job: deploy_for_other_project + - job: integration-test + <<: *teardown_common + # Deploy docs to Pages for review # Docs are staged on this projects pages site pages: stage: docs - except: - - tags - - schedules + allow_failure: true environment: name: review url: https://${CI_PROJECT_NAMESPACE}.${PAGES_DOMAIN}/${CI_PROJECT_NAME}/ tags: - cm-official-docker-executor - dependencies: - - create docs + needs: + - create_docs script: + # create public directory - PUBLIC_DIR='./public' - mkdir -p ${PUBLIC_DIR} # place index.html in public dir @@ -310,23 +458,8 @@ pages: only: - develop - doc-release-branch - -Publish docs to staging: - image: ${CONTAINTHEDOCS_IMAGE} - stage: docs - environment: - name: staging - url: https://clouddocs.f5networks.net/products/extensions/f5-declarative-onboarding/latest - tags: - - cm-official-docker-executor - only: - - docs-staging@automation-toolchain/f5-declarative-onboarding - dependencies: - - create docs - script: - - aws s3 sync docs/_build/html s3://clouddocs.f5networks.net/products/extensions/f5-declarative-onboarding/latest - # create invalidation to clear cloudfront cache - - aws cloudfront create-invalidation --distribution-id $AWS_DIST --paths /products/extensions/f5-declarative-onboarding/latest + - joes-do-wip + coverage: /All files[^|]*\|[^|]*\s+([\d\.]+)/ publish docs to production: image: ${CONTAINTHEDOCS_IMAGE} @@ -340,10 +473,11 @@ publish docs to production: - docs-latest@automation-toolchain/f5-declarative-onboarding tags: - cm-official-docker-executor - dependencies: - - create docs + needs: + - create_docs script: # Publish docs to clouddocs.f5.com (live site). - publish-product-docs-to-prod extensions/f5-declarative-onboarding/latest + - aws s3 cp versions.json s3://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/versions.json # create invalidation to clear cloudfront cache - - aws cloudfront create-invalidation --distribution-id $AWS_DIST --paths /products/extensions/f5-declarative-onboarding + # - aws cloudfront create-invalidation --distribution-id $AWS_DIST --paths /products/extensions/f5-declarative-onboarding diff --git a/.npmrc b/.npmrc index 90d3d2a2..6a012c4e 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1,2 @@ -git-tag-version=false \ No newline at end of file +git-tag-version=false +lockfile-version=1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e27bc64..5af02207 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,371 @@ # Changelog Changes to this project are documented in this file. More detail and links can be found in the Declarative Onboarding [Document Revision History](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/revision-history.html). +## 1.38.0 +### Added +- AUTOTOOL-118: ([Github Issue 9](https://github.com/F5Networks/f5-declarative-onboarding/issues/9)): Support for revoking license on a BIG-IP +- AUTOTOOL-3705: ([GitHub Issue 278](https://github.com/F5Networks/f5-declarative-onboarding/issues/278)): url reference for Authentication ldap sslCaCert property +- AUTOTOOL-3799: Missing protocol values for SnmpUser_authentication and SnmpUser_privacy + +### Fixed + +### Changed + +### Removed + +## 1.37.0 +### Added +- AUTOTOOL-3495: ([Github Issue 304](https://github.com/F5Networks/f5-declarative-onboarding/issues/304)): Support Security Reporting Settings + +### Fixed + +### Changed + +### Removed + +## 1.36.1 +### Added + +### Fixed + +### Changed +- Promoted to LTS + +### Removed + +## 1.36.0 +### Added + +### Fixed + +### Changed +- AUTOTOOL-3609: Change default value for 'allowService' on a 'SelfIp' to 'none' +- AUTOTOOL-2935: Updated vxlan tunnel creation to respect TrafficControl acceptIpOptions values + +### Removed + +## 1.35.0 +### Added +- AUTOTOOL-3526: ([GitHub Issue 324](https://github.com/F5Networks/f5-declarative-onboarding/issues/324)): Add flag to User schema to disable the "enforce password change at first login" policy for the configured user + +### Fixed +- AUTOTOOL-3412: ([GitHub Issue 322](https://github.com/F5Networks/f5-declarative-onboarding/issues/322)): Restarting mcpd may wait for services that are not required +- AUTOTOOL-3555: Configuring TACACS can skip reporting errors +- AUTOTOOL-3558: Issues when there are no Firewall Policies to be processed +- AUTOTOOL-3498: ([GitHub Issue 323](https://github.com/F5Networks/f5-declarative-onboarding/issues/323)): Improve handling on route-domains, by fixing error: "tryuntil error: ioctl failed: No such device" +- AUTOTOOL-3632: Can't refer to other devices in haOrder for a TrafficGroup during HA configuration + +### Changed + +### Removed + +## 1.34.0 +### Added +- AUTOTOOL-3482: ([GitHub Issue 320](https://github.com/F5Networks/f5-declarative-onboarding/issues/320)): Transaction ID in restnoded log output + +### Fixed +- AUTOTOOL-3506: ([partial implementation of GitHub Issue 208](https://github.com/F5Networks/f5-declarative-onboarding/issues/208)): Add sshd KexAlgorithms + +### Changed + +### Removed + +## 1.33.0 +### Added +- AUTOTOOL-3415: ([partial implementation of GitHub Issue 316](https://github.com/F5Networks/f5-declarative-onboarding/issues/316)): Support for auth password policy + +### Fixed +### Changed +- AUTOTOOL-3419: Issue warning when a SelfIp is modified that the default for 'allowService' will change to 'none' in version 1.35.0 +- AUTOTOOL-3057: ([GitHub Issue 297](https://github.com/F5Networks/f5-declarative-onboarding/issues/297)): Declarations with deviceCertificate via BIG-IQ fail + +### Removed + +## 1.32.0 +### Added +- AUTOTOOL-3308: ([GitHub Issue 280](https://github.com/F5Networks/f5-declarative-onboarding/issues/280)): DNS_Resolver_forwardZones/name should accept “.” as FQDN +- AUTOTOOL-3413: ([partial implementation of GitHub Issue 316](https://github.com/F5Networks/f5-declarative-onboarding/issues/316)): Enable/disable and set GUI Security Banner in System class +- AUTOTOOL-3414: ([partial implementation of GitHub Issue 316](https://github.com/F5Networks/f5-declarative-onboarding/issues/316)): Properties to enable/disable SNMP V1 and V2c queries in the SnmpAgent class + +### Fixed +- AUTOTOOL-3346: ([GitHub Issue 314](https://github.com/F5Networks/f5-declarative-onboarding/issues/314)): RemoteAuthRole console property misconfigured when set to disabled +- AUTOTOOL-3337: ([GitHub Issue 308](https://github.com/F5Networks/f5-declarative-onboarding/issues/308)): Fail quicker on bad targetPassphrase value +- AUTOTOOL-3328: ([GitHub Issue 311](https://github.com/F5Networks/f5-declarative-onboarding/issues/311)): GSLBGlobals not processed +- AUTOTOOL-3349: ([Github Issue 315](https://github.com/F5Networks/f5-declarative-onboarding/issues/315)): ManagementRoute Inconsistency + +### Changed +### Removed + +## 1.31.0 +### Added +### Fixed +- AUTOTOOL-3155: ([GitHub Issue 306](https://github.com/F5Networks/f5-declarative-onboarding/issues/306)): DO 1.29.0 unable to find /mgmt/tm/sys/provision +- AUTOTOOL-3323: Improve exception handling when running on BIG-IQ + +### Changed +### Removed + +## 1.30.0 +### Added +- AUTOTOOL-3011: Can now validate with either 'Device' or 'DO' class using do.schema.json + +### Fixed +- AUTOTOOL-3156: Declaration can fail while waiting for unprovisioned service to run +- AUTOTOOL-2850: ([GitHub Issue 279](https://github.com/F5Networks/f5-declarative-onboarding/issues/279)): Management firewall policy does not work without AFM module +- AUTOTOOL-3012: ([GitHub Issue 292](https://github.com/F5Networks/f5-declarative-onboarding/issues/292)): DO unable to change hostname correctly in Google Cloud + +### Changed +### Removed + +## 1.29.0 +### Added +### Fixed +- AUTOTOOL-3040: SelfIp with RouteDomain cannot reach directly connected network +- AUTOTOOL-3051: Licensing can fail if restnoded restarts during processing. +- AUTOTOOL-2845: ([GitHub Issue 276](https://github.com/F5Networks/f5-declarative-onboarding/issues/276)): SelfIp allowService property does not accept a mix of service:port and default +- AUTOTOOL-2881: ([GitHub Issue 282](https://github.com/F5Networks/f5-declarative-onboarding/issues/282)): Security level is not automatically set in SnmpUser class. + +### Changed +### Removed + +## 1.28.0 +### Added +- AUTOTOOL-2871: Allow user to explicitly specify the mgmt-dhcp setting +- AUTOTOOL-2970: routeDomain property to RoutingBGP and RouteMap + +### Fixed +- AUTOTOOL-2612: ([GitHub Issue 248](https://github.com/F5Networks/f5-declarative-onboarding/issues/248)): Licensing in GCP multi-NIC fails (Upgrade to f5-cloud-libs 4.26.7) +- AUTOTOOL-2941: ([GitHub Issue 285](https://github.com/F5Networks/f5-declarative-onboarding/issues/285)): URL is incorrect in schema files + +### Changed +### Removed + +## 1.27.1 +### Added +### Fixed +### Changed +- Promoted to LTS + +### Removed + +## 1.27.0 +### Added + +### Fixed +- AUTOTOOL-2846: ([GitHub Issue 277](https://github.com/F5Networks/f5-declarative-onboarding/issues/277)): Items containing '.' or '-' characters in their names are not passing schema validation +- AUTOTOOL-2930: DNS_Resolver is not idempotent +- AUTOTOOL-2931: Tunnel is not idempotent +- AUTOTOOL-2939: Can't update just the description of ManagementIp +- AUTOTOOL-3006: Can't remove all items of a class + +### Changed +- AUTOTOOL-1898: Several idempotentcy issues are resolved. This required adding defaults for several items in the System class. + +### Removed + +## 1.26.0 +### Added + +### Fixed +- AUTOTOOL-2764: ([GitHub Issue 263](https://github.com/F5Networks/f5-declarative-onboarding/issues/263)): RouteDomain example references objects that do not exist +- AUTOTOOL-2677: ([GitHub Issue 254](https://github.com/F5Networks/f5-declarative-onboarding/issues/254)): Declaration fails when Management IP already exists +- AUTOTOOL-2773: ([GitHub Issue 267](https://github.com/F5Networks/f5-declarative-onboarding/issues/267)): DO fails when a route with a '/' in the name is added manually between DO runs. +- AUTOTOOL-2805: ([GitHub Issue 269](https://github.com/F5Networks/f5-declarative-onboarding/issues/269)): Adding a Management Route Resets Management IP to DHCP. +- AUTOTOOL-2759: ([GitHub Issue 178](https://github.com/F5Networks/f5-declarative-onboarding/issues/178)): Unsupported httpd ciphersuite +- AUTOTOOL-1797: ([GitHub Issue 135](https://github.com/F5Networks/f5-declarative-onboarding/issues/135)): Unable to modify SelfIp referenced by ConfigSync +- AUTOTOOL-2775: GSLBDataCenter does not support remark +- AUTOTOOL-2857: When GTM is enabled, DO returns the error 'Monitor /Common/http is read only' on the second POST even when GSLB is not in the declaration. + +### Changed +### Removed + +## 1.25.0 +### Added +- AUTOTOOL-2750: VXLAN Tunnel Profile support + +### Fixed +- AUTOTOOL-2721: SnmpTrapDestination, SnmpUser, and SnmpCommunity objects cannot be removed once created +- AUTOTOOL-2688: ([GitHub Issue 255](https://github.com/F5Networks/f5-declarative-onboarding/issues/255)): Firewall policies managed by AS3 are not ignored +- AUTOTOOL-2766: ([GitHub Issue 264](https://github.com/F5Networks/f5-declarative-onboarding/issues/264)): Unable to use remote auth user on BIG-IQ to deploy DO declaration +- AUTOTOOL-2768: ([GitHub Issue 265](https://github.com/F5Networks/f5-declarative-onboarding/issues/265)): DO fails when there is pre-existing route configuration with an interface type +- AUTOTOOL-2761: ([GitHub Issue 261](https://github.com/F5Networks/f5-declarative-onboarding/issues/261)): DO always enables dhcp on mgmt interface after post declaration +- AUTOTOOL-2823: ([GitHub Issue 274](https://github.com/F5Networks/f5-declarative-onboarding/issues/274)): Unable to specify gw and target in Route class +- AUTOTOOL-2780: ([GitHub Issue 268](https://github.com/F5Networks/f5-declarative-onboarding/issues/268)): DO 1.24.0 doesn't honor Remote Role Groups "remoteAccess": true setting. Previously working on 1.21.1 +- AUTOTOOL-2882: Unable to POST declaration with single RADIUS server + +### Changed +- AUTOTOOL-2544: Use a default of "UTC" for the timezone property of the NTP class + +### Removed + +## 1.24.0 +### Added +- AUTOTOOL-1156: ([GitHub Issue 98](https://github.com/F5Networks/f5-declarative-onboarding/issues/98), [GitHub Issue 206](https://github.com/F5Networks/f5-declarative-onboarding/issues/206)): GRE and Geneve Tunnel Support +- AUTOTOOL-2668: ([GitHub Issue 236](https://github.com/F5Networks/f5-declarative-onboarding/issues/236)): Added ebgpMultihop to RoutingBGP class +- AUTOTOOL-2675: ([GitHub Issue 241](https://github.com/F5Networks/f5-declarative-onboarding/issues/241)): Add chargeBackTag to License class +- AUTOTOOL-2676: ([GitHub Issue 218](https://github.com/F5Networks/f5-declarative-onboarding/issues/218)): Support for configuring management-ip-rules with ManagementIpFirewall class +- AUTOTOOL-705: SnmpTrapDestination default values for version, port, and network +- AUTOTOOL-2259: RoutingAccessList (net routing access-list) + +### Fixed +- AUTOTOOL-2692: FirewallPolicy incorrectly allows VLANs to be included in the destination schema object + +### Changed +- AUTOTOOL-2528: Truth values in currentConfig response now map to MCP values rather than booleans +- Update f5-cloud-libs to 4.26.3 + - Add failOnErrorMessages and failOnErrorCodes which are arrays of strings/regexes and integers, respectively. That prevent the retry logic from running. Effectively allowing for an early exit of specific failures. + - Add option to provision BIG-IP modules using a transaction + - Fix race condition between createOrModify and MCPD where MCPD first reports an object exists but it has already been deleted. +- AUTOTOOL-2680: Use Transactions for provisioning + +### Removed + +## 1.23.0 +### Added +- AUTOTOOL-2473: ([GitHub Issue 224](https://github.com/F5Networks/f5-declarative-onboarding/issues/224)): Support management IP configuration +- AUTOTOOL-2491: ([GitHub Issue 226](https://github.com/F5Networks/f5-declarative-onboarding/issues/226)): Preserve DHCP routes +- AUTOTOOL-2495: ([GitHub Issue 230](https://github.com/F5Networks/f5-declarative-onboarding/issues/230)): Dry-run support + +### Fixed +- AUTOTOOL-2471: ([GitHub Issue 225](https://github.com/F5Networks/f5-declarative-onboarding/issues/225)): Ability to create type interface routes +- AUTOTOOL-2524: ([GitHub Issue 237](https://github.com/F5Networks/f5-declarative-onboarding/issues/237)): RoutingPrefixList prefixLengthRange does not support strings +- AUTOTOOL-2595: Fix FailoverUnicast unicastAddresses.map is not a function +- AUTOTOOL-2616: ([GitHub Issue 249](https://github.com/F5Networks/f5-declarative-onboarding/issues/249)): RoutingBGP 'toUpperCase' undefined error + +### Changed +- AUTOTOOL-1157: ([GitHub Issue 101](https://github.com/F5Networks/f5-declarative-onboarding/issues/101)): Preserve user authorization keys if no keys were provided in declaration + +### Removed + +## 1.22.0 +### Added +- AUTOTOOL-2509: ([GitHub Issue 220](https://github.com/F5Networks/f5-declarative-onboarding/issues/220)): autoLastHop property to "VLAN" class + +### Fixed +- AUTOTOOL-2476: ([GitHub Issue 227](https://github.com/F5Networks/f5-declarative-onboarding/issues/227)): DO might reboot BIGIP system when same configurations/declaration posted +- AUTOTOOL-2415: ([GitHub Issue 216](https://github.com/F5Networks/f5-declarative-onboarding/issues/216)): Match the accepted "hypervisor" list on DO with what is accepted by BIG-IQ +- AUTOTOOL-2502: ([GitHub Issue 233](https://github.com/F5Networks/f5-declarative-onboarding/issues/233)): DeviceGroup does not work with IPv6 +- AUTOTOOL-2497: ([GitHub Issue 234](https://github.com/F5Networks/f5-declarative-onboarding/issues/234)): Race condition when creating self-ip on non-default route-domain +- AUTOTOOL-2571: Failover Unicast "cannot read property indexOf of undefined" + +### Changed +- AUTOTOOL-531: Properties in the 'traces', 'currentConfig', and 'originalConfig' sections of the response to a request now match what is sent to iControl REST rather than what is in the declaration +- AUTOTOOL-2532: ([GitHub Issue 242](https://github.com/F5Networks/f5-declarative-onboarding/issues/242)): Pull MAC address from management interface instead of the host device MAC address. + +### Removed + +## 1.21.1 +### Added +### Fixed +### Changed +- Promoted to LTS + +### Removed + +## 1.21.0 +### Added +- AUTOTOOL-2433: ([GitHub Issue 221](https://github.com/F5Networks/f5-declarative-onboarding/issues/221)): Configure LDAP referrals + +### Fixed +- AUTOTOOL-2074: ([GitHub Issue 190](https://github.com/F5Networks/f5-declarative-onboarding/issues/190)): Invalid config after upgrading DO from 1.15.0 +- AUTOTOOL-2041: ([GitHub Issue 125](https://github.com/F5Networks/f5-declarative-onboarding/issues/125)): Declaration containing NTP servers by dns name failing in certain cases +- AUTOTOOL-2224: ([GitHub Issue 201](https://github.com/F5Networks/f5-declarative-onboarding/issues/201)): Pre-DO GTM Server preventing DO declaration from running +- AUTOTOOL-2448: ([GitHub Issue 177](https://github.com/F5Networks/f5-declarative-onboarding/issues/177)): Disk class causes errors on declaration update + +### Changed +- AUTOTOOL-2506: Use +nocookie option with dig commands + +### Removed + +## 1.20.0 +### Added +- AUTOTOOL-1991: Added RoutingBGP +- AUTOTOOL-2350: Added FirewallPolicy +- AUTOTOOL-2351: ([GitHub Issue 203](https://github.com/F5Networks/f5-declarative-onboarding/issues/203)): Added FirewallAddressList and FirewallPortList + +### Fixed +- AUTOTOOL-2242: ([GitHub Issue 204](https://github.com/F5Networks/f5-declarative-onboarding/issues/204)): Cannot read property 'applicationData' of undefined +- AUTOTOOL-2080: Task status change after restnoded process restarted +- AUTOTOOL-2215: ([GitHub Issue 198](https://github.com/F5Networks/f5-declarative-onboarding/issues/198)): Allow DeviceGroup owner to be an IPv6 address without having to use a json-pointer. +- Improve schema compatibility with BIG-IQ UI + +### Changed +### Removed + +## 1.19.0 +### Added +- AUTOTOOL-1990: Route Map +- AUTOTOOL-2175: Add support for HTTP GSLB monitor +- AUTOTOOL-2176: GSLB Prober Pool +- AUTOTOOL-2173: Add support for virtual servers in GSLB server +- AUTOTOOL-2180: GSLB Monitors (Remaining) + +### Fixed +### Changed +- AUTOTOOL-1238: ([GitHub Issue 118](https://github.com/F5Networks/f5-declarative-onboarding/issues/118)): Improve behavior when tenant is missing + +### Removed + +## 1.18.0 +### Added +- AUTOTOOL-2002: GSLB Data Center +- AUTOTOOL-2001: GSLB Server +- AUTOTOOL-1654: Routing Prefix List +- AUTOTOOL-2058: ([GitHub Issue 179](https://github.com/F5Networks/f5-declarative-onboarding/issues/179)): Add support for specifying BIG-IQ auth provider for licensing. +- AUTOTOOL-1882: Log version on startup + +### Fixed +- AUTOTOOL-1799: ([GitHub Issue 149](https://github.com/F5Networks/f5-declarative-onboarding/issues/149)): Can only create one DeviceGroup +- AUTOTOOL-2139: GSLB schema defaults are not applied in some cases + +### Changed +### Removed + +## 1.17.0 +### Added +- AUTOTOOL-1373: ([GitHub Issue 128](https://github.com/F5Networks/f5-declarative-onboarding/issues/128)): Support Failover Multicast on the BIG-IPs default device. +- AUTOTOOL-1923: ([GitHub Issue 164](https://github.com/F5Networks/f5-declarative-onboarding/issues/164)): Rudimentary DeviceCertificate validation +- AUTOTOOL-1943: ([GitHub Issue 156](https://github.com/F5Networks/f5-declarative-onboarding/issues/156)): Allow variable expressions in some RemoteAuthRole fields +- AUTOTOOL-1532: ([GitHub Issue 143](https://github.com/F5Networks/f5-declarative-onboarding/issues/143)): Parent property to RouteDomain +- AUTOTOOL-2003: Configure global GSLB settings + +### Fixed +- AUTOTOOL-1942: RemoteAuthRole remoteAccess property logic is backwards +- AUTOTOOL-1955: ([GitHub Issue 177](https://github.com/F5Networks/f5-declarative-onboarding/issues/177)): Disk size must be larger than current size +- AUTOTOOL-1798: ([GitHub Issue 140](https://github.com/F5Networks/f5-declarative-onboarding/issues/140)): Unable to specify route domain in route gw address + +### Changed +- AUTOTOOL-1924: ([GitHub Issue 163](https://github.com/F5Networks/f5-declarative-onboarding/issues/163)): Accept 'all' as a single word for HTTPD allow value + +### Removed + +## 1.16.0 +### Added +- AUTOTOOL-1652: Add support for routing as-path +- AUTOTOOL-1374: ([GitHub Issue 112](https://github.com/F5Networks/f5-declarative-onboarding/issues/112)): Add support for MirrorIp class +- AUTOTOOL-1577: Add support for LDAPS certificate settings + +### Fixed +- AUTOTOOL-1990: Retry license install if we get a connection reset +- Target VLAN errors from the inspect endpoint +- AUTOTOOL-1899: Fix minor schema issues. No type for minPathMtu and use const for Tunnel class +- AUTOTOOL-1845: ([GitHub Issue 147](https://github.com/F5Networks/f5-declarative-onboarding/issues/147)): Route creation order can be incorrect + +### Changed +### Removed + ## 1.15.0 ### Added +- AUTOTOOL-530: Add Trace files for debug printing - AUTOTOOL-1307: ([GitHub Issue 111](https://github.com/F5Networks/f5-declarative-onboarding/issues/111)): Add support for SSHD allowed source IP's +- AUTOTOOL-1635: ([GitHub Issue 72](https://github.com/F5Networks/f5-declarative-onboarding/issues/72)): Support tenant property when licensing +- AUTOTOOL-1675: ([GitHub Issue 152](https://github.com/F5Networks/f5-declarative-onboarding/issues/152)): Add support for creating and configuring multiple failover unicasts +- AUTOTOOL-1206: Add experimental support for resizing appdata +- AUTOTOOL-1749: ([GitHub Issue 141](https://github.com/F5Networks/f5-declarative-onboarding/issues/141)): Add support for creating routes on the LOCAL_ONLY partition. + ### Fixed +- Improve schema for use with BIG-IQ 7.1 + ### Changed ### Removed @@ -14,11 +375,14 @@ Changes to this project are documented in this file. More detail and links can b - AUTOTOOL-1610: Add support for VLAN failsafe settings - AUTOTOOL-1358: ([GitHub Issue 123](https://github.com/F5Networks/f5-declarative-onboarding/issues/123)): TCP Forward Tunnel Support - AUTOTOOL-1609: Add support for creating and configuring traffic groups + ### Fixed - AUTOTOOL-1091: Bad class values do not fail schema validation - AUTOTOOL-1659: MAC_Masquerade fails to roll back properly + ### Changed - AUTOTOOL-1521: Update npm packages + ### Removed ## 1.13.0 @@ -29,17 +393,21 @@ Changes to this project are documented in this file. More detail and links can b - AUTOTOOL-1236: ([GitHub Issue 107](https://github.com/F5Networks/f5-declarative-onboarding/issues/107)): Add support for System autoCheck setting - AUTOTOOL-1248: ([GitHub Issue 120](https://github.com/F5Networks/f5-declarative-onboarding/issues/120)): Add support for System tmshAuditLog and guiAuditLog - AUTOTOOL-1322: ([GitHub Issue 96](https://github.com/F5Networks/f5-declarative-onboarding/issues/96)): Support generated MAC Masquerade on Traffic Groups according to https://support.f5.com/csp/article/K3523. + ### Fixed - AUTOTOOL-1491 ([GitHub Issue 138](https://github.com/F5Networks/f5-declarative-onboarding/issues/138)): Cannot create a device group with AFM provisioned - AUTOTOOL-1469: Problems with latest Azure image - AUTOTOOL-901 ([GitHub Issue 79](https://github.com/F5Networks/f5-declarative-onboarding/issues/79)): charset not allowed in Content-Type header + ### Changed - Update @f5devcentral/f5-teem package dependency to 1.4.6 + ### Removed ## 1.12.0 ### Added - AUTOTOOL-152: Ability to upload device certificate + ### Fixed - AUTOTOOL-1094 ([GitHub Issue 91](https://github.com/F5Networks/f5-declarative-onboarding/issues/91)): Provisioning fails if module does not exist on box - AUTOTOOL-1170: Call webhook after declaration requiring reboot @@ -47,52 +415,64 @@ Changes to this project are documented in this file. More detail and links can b - AUTOTOOL-1440 ([GitHub Issue 132](https://github.com/F5Networks/f5-declarative-onboarding/issues/132)): Schema is incompatible with golang regexp - AUTOTOOL-902 ([GitHub Issue 81](https://github.com/F5Networks/f5-declarative-onboarding/issues/81)): Added missing roles for RemoteAuthRole.role enum - [GitHub Issue 103](https://github.com/F5Networks/f5-declarative-onboarding/issues/103): Avoid deleting dos-global-dg device group + ### Changed - AUTOTOOL-1014: Update to f5-teem 1.4.2 + ### Removed ## 1.11.1 ### Added ### Fixed - AUTOTOOL-1388: Fix allowed schema versions + ### Changed ### Removed ## 1.11.0 ### Added - AUTOTOOL-1223: Allow provisioning SSLO module + ### Fixed - AUTOTOOL-1139 ([GitHub Issue 100](https://github.com/F5Networks/f5-declarative-onboarding/issues/100)): Route Configuration can conflict with DHCP - AUTOTOOL-1125 ([GitHub Issue 104](https://github.com/F5Networks/f5-declarative-onboarding/issues/104)): Setting ConfigSync does not handle device name / hostname mismatch and ([GitHub Issue 113](https://github.com/F5Networks/f5-declarative-onboarding/issues/113)): Attempting to modify ConfigSync on non-existing device - device not resolving properly - AUTOTOOL-1166: Requiring a reboot causes task to never complete - AUTOTOOL-1235: Relicensing BIG-IP can be interrupted by service restart + ### Changed - AUTOTOOL-1124: Allow IP addresses for configuring cluster members + ### Removed ## 1.10.0 ### Added - AUTOTOOL-993: Add support for System autoPhonehome setting - AUTOTOOL-916: Add support for provisioning CGNAT on BIG-IP v15.0+ + ### Fixed - AUTOTOOL-343: On BIG-IP 14+, revoke license from BIG-IQ does not work - Make sure config is saved before issuing revoke command - Fix issue when existing radius servers are present and none are the primary + ### Changed - AUTOTOOL-903: Integration test improvements: Run integration tests against BIG-IP 13.1, 14.0 and 14.1 instances + ### Removed ## 1.9.0 ### Added - AUTOTOOL-910: Add query parameter {statusCodes: 'experimental'} to enable new status codes as implemented in AUTOTOOL-727 + ### Fixed - AUTOTOOL-807: Fix bug in which DO was unable to set hostname in AWS environment (K45728203) - AUTOTOOL-806: Fix bug in which changes to the network property for ManagementRoute and Route would not actually update the config [Issue 75](https://github.com/F5Networks/f5-declarative-onboarding/issues/75) - AUTOTOOL-904: Fix /example endpoint + ### Changed - AUTOTOOL-727: Changed HTTP status for GET requests to be 200 unless something goes wrong with the actual request. The results of the request will contain the status. (This change could break compatibility with previous versions) - AUTOTOOL-855: Updated packages - AUTOTOOL-945: Integration test improvements: Debug logs are now written to test/logs. Retry when getting current assignments from BIG-IQ. + ### Removed ## 1.8.0 @@ -101,11 +481,13 @@ Changes to this project are documented in this file. More detail and links can b - Add support for HTTPD class [Issue 50](https://github.com/F5Networks/f5-declarative-onboarding/issues/50) - AUTOTOOL-708: Add support for cliInactivityTimeout, consoleInactivityTimeout, and hostname in System class - AUTOTOOL-747: Add Declarative Onboarding analytics reporting to F5 + ### Fixed - Fix bug in which DO was unable to use management network for SnmpTrapDestination - Fix bug in which DO creates incomplete RADIUS authentication configuration - Fix bug in which DO was unable to remove Radius System Auth configuration - Fix bug in which DO doesn't remove secondary Radius server when it is absent in declaration + ### Changed ### Removed @@ -124,12 +506,14 @@ Changes to this project are documented in this file. More detail and links can b - Add support for cmp-hash for VLAN [Issue 1](https://github.com/F5Networks/f5-declarative-onboarding/issues/1) - Add support for Traffic Control - Add support for Trunk class + ### Fixed - Resolve [Issue 53](https://github.com/F5Networks/f5-declarative-onboarding/issues/53) - Resolve [Issue 60](https://github.com/F5Networks/f5-declarative-onboarding/issues/60) - Resolve [Issue 67](https://github.com/F5Networks/f5-declarative-onboarding/issues/67) - Fix bug in which DO sets task status to ERROR right away while it is still rolling back - Fix bug in which DO was unable to create new VLAN(s) when no Route Domain(s) specified in declaration. Now DO will add new VLAN(s) to Route Domain with ID 0 unless otherwise specified. + ### Changed - Allow 'none' as valid value for configsyncIp (ConfigSync class) - Handle the automatic update of root password when admin password changes on 14.0 and later @@ -137,6 +521,7 @@ Changes to this project are documented in this file. More detail and links can b - When targetSshKey is used try bash shell to modify targetUsername password if tmsh shell fails. - Improve masking of nested secrets - Improve Route Domains handling + ### Removed ## 1.6.1 @@ -144,16 +529,19 @@ Changes to this project are documented in this file. More detail and links can b ### Fixed ### Changed - Upgrade f5-cloud-libs to improve licensing from BIG-IQ reg key pools + ### Removed ## 1.6.0 ### Added - Add support for Management Route - Add support for Route Domains [Issue 10](https://github.com/F5Networks/f5-declarative-onboarding/issues/10) + ### Fixed - Resolve [Issue 36](https://github.com/F5Networks/f5-declarative-onboarding/issues/36) - Resolve [Issue 43](https://github.com/F5Networks/f5-declarative-onboarding/issues/43) - Resolve [Issue 28](https://github.com/F5Networks/f5-declarative-onboarding/issues/28) + ### Changed ### Removed @@ -162,6 +550,7 @@ Changes to this project are documented in this file. More detail and links can b ### Fixed ### Changed - When running on BIG-IQ, poll TCW longer to match the TCW timeout + ### Removed ## 1.5.0 @@ -170,6 +559,7 @@ Changes to this project are documented in this file. More detail and links can b - Add Authorized Keys capability to user declarations. - Allow setting global analytics settings. - Resolve [Issue 35](https://github.com/F5Networks/f5-declarative-onboarding/issues/35) + ### Fixed - Resolve [Issue 14](https://github.com/F5Networks/f5-declarative-onboarding/issues/14) - Resolve [Issue 26](https://github.com/F5Networks/f5-declarative-onboarding/issues/26) @@ -177,10 +567,12 @@ Changes to this project are documented in this file. More detail and links can b - Fix bug in which credentials could appear in declaration results when revoking a license. - Fix issue in which initial clustering failure would prevent clustering from working on subsequent attempts due to using the wrong device name (resolved in f5-cloud-libs). - LicensePool now respects custom management access port of BIG-IP that is being licensed. + ### Changed - Disable DHCP for DNS/NTP if DO will be configuring them. - RADIUS server secret will no longer appear in the log. - When a 400 is received from restjavad, DO will now retry licensing. + ### Removed - License keys will no longer appear in the log. @@ -188,6 +580,7 @@ Changes to this project are documented in this file. More detail and links can b ### Added ### Fixed - Fix vulnerability CVE-2019-5021 in DO container + ### Changed ### Removed @@ -197,6 +590,7 @@ Changes to this project are documented in this file. More detail and links can b - taskId is now returned from POST onboard requests - New /task API to retrieve status by task - Initial port to run on BIG-IQ for use in onboarding BIG-IP from BIG-IQ + ### Fixed ### Changed ### Removed @@ -209,6 +603,7 @@ Changes to this project are documented in this file. More detail and links can b - Resolve [Issue 18](https://github.com/F5Networks/f5-declarative-onboarding/issues/18) - Resolve [Issue 21](https://github.com/F5Networks/f5-declarative-onboarding/issues/21) - Resolve [Issue 32](https://github.com/F5Networks/f5-declarative-onboarding/issues/32) + ### Changed ### Removed @@ -217,19 +612,24 @@ Changes to this project are documented in this file. More detail and links can b - Add 'overwrite' option when licensing via BIG-IQ - Allow for licenses to be revoked when licensed via BIG-IQ - Allow modification of a SelfIp address + ### Fixed - Fix bug in which all self ips would be updated if there was a change to any of them - Fix bug in which clustering was not working if ASM was provisioned + ### Changed - Allow $schema property for use in local validation of declaration + ### Removed ## 1.2.0 ### Added - Support for remote provisioning via ASG. + ### Fixed - Fix bug which rejected CIDR of 1x on SelfIp. - Fix bug in which DB vars are not rolled back in the event of an error + ### Changed ### Removed @@ -237,11 +637,13 @@ Changes to this project are documented in this file. More detail and links can b ### Added - Support licensing via BIG-IQ utility, purchased, and reg key pools. - Allow setting global db variables. + ### Fixed - Fix clustering race condition when onboarding 2 devices at the same time. - Fix bug which was improperly deleting objects which just had a property change. - Fix issue where device name was not being set if hostname already matched declaration. - Ensure that non-floating self IPs are created before floating self IPs. + ### Changed - Allow partition access 'all-partitions' when creating regular users. - Allow shell of 'none' when creating regular users. @@ -249,6 +651,7 @@ Changes to this project are documented in this file. More detail and links can b - Apply defaults from the schema. - Dis-allow sync-failover device group with both autoSync and fullLoadOnSync. - Handle missing content-type header. + ### Removed ## 1.0.0 diff --git a/Makefile b/Makefile index 79215896..c2fb69d0 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,10 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - + npm ci + node scripts/build/schema-build.js + node scripts/build/schema-check.js + node scripts/build/schema-to-rst.js @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # Custom commands for building and testing project documentation diff --git a/README.md b/README.md index 51456395..fa2ce07d 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,31 @@ -# F5 Declarative Onboarding +# F5 BIG-IP Declarative Onboarding -[![Slack Status](https://f5cloudsolutions.herokuapp.com/badge.svg)](https://f5cloudsolutions.herokuapp.com) [![Releases](https://img.shields.io/github/release/F5Networks/f5-declarative-onboarding.svg)](https://github.com/F5Networks/f5-declarative-onboarding/releases) [![Issues](https://img.shields.io/github/issues/F5Networks/f5-declarative-onboarding.svg)](https://github.com/F5Networks/f5-declarative-onboarding/issues) ## Introduction -F5 Declarative onboarding uses a declarative model to initially configure a BIG-IP device with all of the required settings to get up and running. This includes system settings such as licensing and provisioning, network settings such as VLANs and Self IPs, and clustering settings if you are using more than one BIG-IP system. +F5 BIG-IP Declarative Onboarding uses a declarative model to initially configure a F5 BIG-IP device with all of the required settings to get up and running. This includes system settings such as licensing and provisioning, network settings such as VLANs and Self IPs, and clustering settings if you are using more than one BIG-IP system. -**IMPORTANT** Beginning with DO 1.8.0, the DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in this repository. These files can be found on the [Release page](https://github.com/F5Networks/f5-declarative-onboarding/releases), as **Assets**. +**IMPORTANT** Beginning with F5 BIG-IP DO 1.8.0, the DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in this repository. These files can be found on the [Release page](https://github.com/F5Networks/f5-declarative-onboarding/releases), as **Assets**. ## Documentation -For the documentation on Declarative Onboarding, including download, installation, and usage instructions, see the Declarative Onboarding [User Guide](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest). +For documentation on F5 BIG-IP Declarative Onboarding, including download, installation, and usage instructions, see the Declarative Onboarding [User Guide](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest). -### Example Declarative Onboarding declarations +### Example F5 BIG-IP Declarative Onboarding declarations The Declarative Onboarding documentation contains example declarations you can modify to suit your needs. See the [Examples](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/examples.html) page. ## Filing Issues and Getting Help -If you come across a bug or other issue when using Declarative Onboarding, use [GitHub Issues](https://github.com/F5Networks/f5-declarative-onboarding/issues) to submit an issue for our team. You can also see the current known issues on that page, which are tagged with a purple Known Issue label. **Important**: Github Issues are consistently monitored by F5 staff, but should be considered as best effort only and you should not expect to receive the same level of response as provided by F5 Support. Please open a case as described below with F5 if this is a critical issue. +If you come across a bug or other issue when using BIG-IP Declarative Onboarding, use [GitHub Issues](https://github.com/F5Networks/f5-declarative-onboarding/issues) to submit an issue for our team. You can also see the current known issues on that page, which are tagged with a purple Known Issue label. -Because Declarative Onboarding v1.1.0 and later has been created and fully tested by F5 Networks, it is fully supported by F5. This means you can get assistance if necessary from [F5 Technical Support](https://support.f5.com/csp/article/K25327565). +**Important**: Github Issues are consistently monitored by F5 staff, but should be considered as best effort only and you should not expect to receive the same level of response as provided by F5 Support. Please open a case as described below with F5 if this is a critical issue. -Be sure to see the [Support page](SUPPORT.md) in this repo for more details and supported versions of Declarative Onboarding. +Because BIG-IP Declarative Onboarding versions 1.1.0 and later have been created and fully tested by F5 Networks, they are is fully supported by F5. This means you can get assistance if necessary from [F5 Technical Support](https://support.f5.com/csp/article/K25327565). -### Community Help -We encourage you to use our [Slack channel](https://f5cloudsolutions.herokuapp.com) for discussion and assistance on Declarative Onboarding templates (click the **declarative-onboard** channel). There are F5 employees who are members of this community who typically monitor the channel Monday-Friday 9-5 PST and will offer best-effort assistance. See the [Slack Channel Statement](slack-channel-statement.md) for guidelines on using this channel. +Be sure to see the [Support page](SUPPORT.md) in this repo for more details and supported versions of BIG-IP Declarative Onboarding. ## Copyright -Copyright 2014-2020 F5 Networks Inc. - +Copyright 2014-2023 F5 Networks Inc. ### F5 Networks Contributor License Agreement @@ -39,5 +36,3 @@ If you are signing as an individual, we recommend that you talk to your employer If your employer has rights to intellectual property that you create, such as your contributions, you represent that you have received permission to make contributions on behalf of that employer, that your employer has waived such rights for your contributions, or that your employer has executed a separate CLA with F5. If you are signing on behalf of a company, you represent that you are legally entitled to grant the license recited therein. You represent further that each employee of the entity that submits contributions is authorized to submit such contributions on behalf of the entity pursuant to the CLA. - - diff --git a/SUPPORT.md b/SUPPORT.md index 918e1c89..a1277009 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -11,16 +11,15 @@ Declarative Onboarding Extension (DO) Software Lifecycle: Currently supported versions: -| Software Version | Release Type | First Customer Ship |End of Support | +| Software Version | Release Type | First Customer Ship | End of Support | |------------------|---------------|---------------------|-----------------| -| DO 1.11.1 | Fix* | 30-Mar-2020 | 10-Jun-2020 | -| DO 1.12.0 | Feature | 21-Apr-2020 | 21-Jul-2020 | -| DO 1.13.0 | Feature | 02-Jun-2020 | 02-Sep-2020 | -| DO 1.14.0 | Feature | 21-Jul-2020 | 21-Oct-2020 | - -\* Fix for Allowed schema version +| DO 1.36.0 | Feature | 09-Feb-2023 | 09-May-2023 | +| DO 1.36.1 | LTS | 09-Mar-2023 | 09-Mar-2024 | +| DO 1.37.0 | Feature | 27-Mar-2022 | 27-Jun-2023 | +| DO 1.38.0 | Feature | 22-May-2023 | 22-Aug-2023 | +\* Fix for Allowed schema version Versions no longer supported: @@ -28,9 +27,9 @@ Versions no longer supported: |------------------|---------------|---------------------|-----------------| | DO 1.1.0 | Feature | 20-Dec-2018 | 20-Mar-2019 | | DO 1.2.0 | Feature | 16-Jan-2019 | 16-Apr-2019 | -| DO 1.3.0 | Feature | 27-Feb-2019 | 27-May-2019 | -| DO 1.3.1 | Feature | 07-May-2019 | 07-Aug-2019 | -| DO 1.4.0 | Feature | 08-May-2019 | 08-Aug-2019 | +| DO 1.3.0 | Feature | 27-Feb-2019 | 27-May-2019 | +| DO 1.3.1 | Feature | 07-May-2019 | 07-Aug-2019 | +| DO 1.4.0 | Feature | 08-May-2019 | 08-Aug-2019 | | DO 1.4.1 | Fix* | 21-May-2019 | 08-Aug-2019 | | DO 1.5.0 | Feature | 18-Jun-2019 | 18-Sep-2019 | | DO 1.6.0 | Feature | 30-Jul-2019 | 30-Oct-2019 | @@ -39,8 +38,34 @@ Versions no longer supported: | DO 1.9.0 | Feature | 03-Dec-2019 | 03-Mar-2020 | | DO 1.10.0 | Feature | 27-Jan-2020 | 27-Apr-2020 | | DO 1.11.0 | Feature | 10-Mar-2020 | 10-Jun-2020 | +| DO 1.11.1 | Fix* | 30-Mar-2020 | 10-Jun-2020 | +| DO 1.12.0 | Feature | 21-Apr-2020 | 21-Jul-2020 | +| DO 1.13.0 | Feature | 02-Jun-2020 | 02-Sep-2020 | +| DO 1.14.0 | Feature | 21-Jul-2020 | 21-Oct-2020 | +| DO 1.15.0 | Feature | 01-Sep-2020 | 01-Dec-2020 | +| DO 1.16.0 | Feature | 13-Oct-2020 | 13-Jan-2021 | +| DO 1.17.0 | Feature | 20-Nov-2020 | 20-Feb-2021 | +| DO 1.18.0 | Feature | 12-Jan-2021 | 12-Apr-2021 | +| DO 1.19.0 | Feature | 23-Feb-2021 | 23-May-2021 | +| DO 1.20.0 | Feature | 06-Apr-2021 | 06-Jul-2021 | +| DO 1.21.0 | Feature | 18-May-2021 | 18-Aug-2021 | +| DO 1.22.0 | Feature | 29-Jun-2021 | 29-Sep-2021 | +| DO 1.23.0 | Feature | 09-Aug-2021 | 09-Nov-2021 | +| DO 1.24.0 | Feature | 21-Sep-2021 | 21-Dec-2021 | +| DO 1.25.0 | Feature | 02-Nov-2021 | 02-Feb-2022 | +| DO 1.26.0 | Feature | 14-Dec-2021 | 14-Mar-2022 | +| DO 1.27.0 | Feature | 25-Jan-2022 | 25-Apr-2022 | +| DO 1.28.0 | Feature | 08-Mar-2022 | 02-Jun-2022 | +| DO 1.21.1 | LTS | 23-Jun-2021 | 23-Jun-2022 | +| DO 1.29.0 | Feature | 19-Apr-2022 | 19-Jul-2022 | +| DO 1.30.0 | Feature | 31-May-2022 | 31-Aug-2022 | +| DO 1.31.0 | Feature | 15-Jul-2022 | 15-Oct-2022 | +| DO 1.32.0 | Feature | 23-Aug-2022 | 23-Nov-2022 | +| DO 1.33.0 | Feature | 04-Oct-2022 | 04-Jan-2023 | +| DO 1.27.1 | LTS | 08-Mar-2022 | 08-Mar-2023 | +| DO 1.34.0 | Feature | 15-Nov-2022 | 15-Feb-2023 | +| DO 1.35.0 | Feature | 12-Jan-2023 | 12-Apr-2023 | \* Fix for updated Docker Container packaging only -See the [Release notes](https://github.com/F5Networks/f5-declarative-onboarding/releases) and [Declarative Onboarding documentation](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/) for new features and issues resolved for each release. - +See the [Release notes](https://github.com/F5Networks/f5-declarative-onboarding/releases) and [Declarative Onboarding documentation](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/) for new features and issues resolved for each release. \ No newline at end of file diff --git a/contributing/README.md b/contributing/README.md index 2a33c03e..e9a0d4b5 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -21,7 +21,7 @@ on a BIG-IP, as well as from BIG-IQ and the Application Services Gateway contain How does the project handle a typical `POST` request? -`POST /mgmt/shared/telemetry/declare` +`POST /mgmt/shared/declarative-onboarding` ```json { @@ -301,6 +301,23 @@ What happens in the system internals between request and response? - All configuration is handled via iControl REST. - Heavy lifting provided by f5-cloud-libs. +--- +#### Anatomy of a Request on BIG-IQ +When running on BIG-IQ, the processing happens mostly on BIG-IQ. DO uses iControl REST requests to get configuration and put configuration on the target BIG-IP device. Unlike AS3, DO does not have to be installed on the BIG-IP. + +BIG-IQ has a UI to show the user the status of requests. Also, we want the API on BIG-IQ to look just like on BIG-IP from a user perspective. Because of this, DO on BIG-IQ receives requests directly from the user but has to do extra processing to allow BIG-IQ to update it's UI. Here is the basic flow +* User posts declaration to DO on BIG-IQ +* DO returns taskId to user +* User starts polling DO for status of task +* DO forwards declaration to the task collection worker (TCW) which is a BIG-IQ process +* TCW does what it needs to do to keep the BIG-IQ UI up to date +* TCW posts the same declaration back to DO +* DO returns a separate taskId to TCW +* TCW polls DO for task status +* DO processes declararation +* DO polls TCW for its status (which is updated when TCW polling hears from DO that it is done) +* When DO polling learns that TCW is done, DO updates original user taskId with status + --- ## Contributing @@ -349,7 +366,21 @@ Build/publish makes heavy use of GitLab and [.gitlab-ci.yml](../.gitlab-ci.yml). - .json and.js files in /schema should be copied into latest. - A new directory should be added for the new release version. - RPMs are generated for every push to GitLab. -- RPMs are pushed to Artifactory at f5-declarative-onboarding-rpm for every tag pushed to GitLab. +- RPMs are pushed to Artifactory at f5-automation-toolchain-generic/f5-declarative-onboarding for every tag pushed to GitLab. - When ready for release: - RPM should be manually copied into dist and pushed back up to GitLab. Please let's stop doing this. - - RPM should be manually added to the F5 CDN. Please let's automate this. \ No newline at end of file + - RPM should be manually added to the F5 CDN. Please let's automate this. + +--- +### GitLab Push Rules + +To prevent the releasing of private or sensative information we automatically prevent certain strings from being included in commit messages. + +If modifications are necessary open the GitLab GUI, then Settings -> Repository -> Push Rules -> "Commit message negative match". + +When you attempt to push a commit message that contains sensitive information, you will see the following error: `Commit message contains the forbidden pattern` + +We check for the following: +- Email addresses +- IP addresses +- Generic credential keywords diff --git a/contributing/process_local_doc_build.md b/contributing/process_local_doc_build.md new file mode 100644 index 00000000..ef8d67c9 --- /dev/null +++ b/contributing/process_local_doc_build.md @@ -0,0 +1,19 @@ +# How to build documentation locally +1. Create a Python virtual enviornment: +```bash +virtualenv venv +``` +2. Activate the virutal environemnt: +```bash +source venv/bin/activate +``` +3. Install Python dependencies to the virtual environment: +```bash +pip install -r requirements.txt +``` +4. Use the Makefile to build documentation as HTML: +```bash +make html +``` + +After the first time doing this, only steps 2 and 4 should be necessary to build documentation locally. diff --git a/contributing/process_release.md b/contributing/process_release.md index 3eed663a..ceb4f175 100644 --- a/contributing/process_release.md +++ b/contributing/process_release.md @@ -5,42 +5,115 @@ * RPM * RPM sha256 checksum * Postman collection of examples - * ASG Docker container * RPM is built in every pipeline run, and is kept in GitLab for one week -* On a Git tag, RPM is published to Artifactory (f5-declarative-onboarding-rpm) +* On a Git tag, RPM is published to Artifactory (f5-automation-toolchain-generic/f5-declarative-onboarding) ## Release Notes -* Release notes are tracked during development in RELEASE_NOTES.md - -## Process for release candidates -* Determine version - * \ should be value found in package.json (e.g. 1.13.0-1) - * \ is \ but only the major, minor, and patch numbers (e.g. 1.13.0) -* git checkout develop (or whichever branch you want to make a tag of) -* mkdir src/schema/\ -* cp src/schema/latest/* src/schema/\ -* git add and commit -* git tag -m 'Release candidate ' v\ -* git push origin -* git push origin --tags -* Update package.json and package-lock.json with next version (for example: X.Y+1.0, or X.Y.Z-#+1) -* git add and commit -* git push origin - -## Process for release (assuming git remote 'github' points to GihHub) -* git tag -m 'Release X.Y.Z' vX.Y.Z -* git push -* git push --tags -* git checkout master -* git merge -* git checkout develop -* git merge -* git push origin -* git push origin --tags -* git push github -* git push github --tags -* Download ASG artifact and expand it -* docker load --input /dist/f5devcentral-f5-do-container-X.Y.Z.tar.gz -* docker push f5devcentral/f5-do-container:X.Y.Z -* docker tag f5devcentral/f5-do-container:X.Y.Z f5devcentral/f5-do-container:latest -* docker push f5devcentral/f5-do-container:latest +* Release notes are tracked during development in `CHANGELOG.md` + +## Process for LTS release +* Using the GitLab GUI, create a branch from the release branch that we are declaring LTS. Bump the patch version by 1. For example, if we are declaring 1.36.0 to be LTS, then create a 1.36.1 branch from 1.36.0. +* On your local machine, fetch and checkout the LTS branch. +* Create a new local branch from the LTS branch (e.g. "prepare-1.36.1-release"). +* Update the patch version in `package.json` and `package-lock.json`. The release number of the new version should start at 0 (e.g. 1.36.0-4 would become 1.36.1-0). +* Add a new CHANGELOG section that looks like + ``` + ## 1.36.1 + ### Added + + ### Fixed + + ### Changed + - Promoted to LTS + + ### Removed + ``` +* Create an MR for these changes. Important: Remember to set the branch you are merging into to the LTS branch. +* Go to the atg-build project in GitLab + * Edit the DO schedule to set the `gitBranch` variable to the LTS branch. + * Run the DO schedule. + * After the build completes, edit the DO schedule to set the `gitBranch` variable back to develop. +* Using the GUI create a tag off the LTS branch (e.g. 1.36.1) + * In the GUI go to `Repository -> Tags -> New tag`. + * The name of the tag should be the LTS version with a 'v' at the front (e.g. v1.36.1). + * Update the `createFrom` to point at the LTS branch. + * Set the message to: `LTS release v` (e.g. "LTS release v1.36.1") +* Merge the LTS branch (without updating the package version) into develop and create an MR for this. +* Merge the LTS branch (only update package version if LTS is latest) into master and create an MR for this. + +## Process for release +### Begin process release at the very beginning of the first sprint of a new release, by performing the following actions +* Determine the `` by using the major version, minor version, and patch number as the name (e.g 1.35.0). +* Create a new release branch with the name: ``. + * Using the GitLab UI, create the branch from `develop` to avoid any issues with an out-of-date local repository +* Update the release branch's schema via the following steps: + * `git pull` + * `git checkout ` + * `mkdir -p src/schema/` + * `cp src/schema/latest/* src/schema/` + * git add and commit + * `git push origin` +* Point the `gitBranch` variable in the DO schedule in the atg-build repository at the release branch +* Run the DO schedule from the atg-build repository in GitLab. This will: + * Update and commit build number changes to `package.json` and `package-lock.json` + * Tag the appropriate branch with the updated `-` (e.g. v1.35.0-4) + * Upload the build to Artifactory + * Send an email to the team with build details +* Point the `gitBranch` variable in the AS3 schedule in the atg-build repository back to `develop` +* Prepare the `develop` branch for the next development cycle + * `git checkout develop` + * `git pull` + * Determine the `` by incrementing the minor release number, and setting the patch number to 0 (e.g. 1.35.0 becomes 1.36.0). + * `get checkout -b bump-to-` + * `git checkout src/schema/` + * This pulls in the new schema directory from the release branch + * Edit package.json and package-lock.json to `-0` (e.g. 1.36.0-0). + * Update the `info.version` property in `src/schema/latest/openapi.yaml` to `` (e.g. 1.36.0). + * Add `` to the `schemaVersion` array in `src/schema/latest/base.schema.json`. + * Adding a new block to `CHANGELOG.md` with the following content: + ``` + ## + ### Added + + ### Fixed + + ### Changed + + ### Removed + ``` + * git add, commit, and push. + * Submit an MR for these changes and wait for approval. +* Perform the "Actions on night before Go/No-Go meeting". +* Perform the "Actions after go ahead from Go/No-Go meeting". + +### Actions on night before Go/No-Go meeting: +* Using the GUI, create 2 MRs + * 1 MR to merge release branch to `master`. + * 1 MR to merge release branch to `develop`. + * Do not squash commits. + * Do not delete branch. + * You can self-approve and merge these MRs. + * Note: If the GUI suggests a rebase, do a merge locally instead (see below). DO NOT TRUST the GUI rebase tool, it lies! + * `git checkout ` + * `git pull` + * `git checkout -b merge--to-` + * `git merge ` + * `git push` + * Via GUI, create an MR to merge this into `` +* Using the GUI, create a tag on the `master` branch in the format `v` (e.g. `v1.34.0`). +### Actions after go ahead from Go/No-Go meeting: +* Confirm with Hannah things are good to go. +* Close your Jira task when the release is complete. + +## Documentation Release process +* After the third sprint is finished and the release branch has been created, checkout out the dev release branch and then merge it into **doc-release-branch**. +* Make any additions or modifications to the **doc-release-branch** for items specific to the release. + * Update the release version in the **conf.py** file. + * Update the latest version in the **versions.json** files (in doc-release branch and any LTS doc branches (for example **docs-3.36.1**, and **doc-3.32.1**)). Do NOT push the versions.json file for the LTS branches until the release has gone out. + * Update the support.md file if applicable (currently not applicable for AS3, but is applicable for DO) + * Make sure the **revision-history.rst** file is up-to-date with all work done and the Issues resolved from the changelog.md file. +* On release day, wait for the announcement that the code has been pushed to Github. +* Checkout out **docs-latest**, and then merge the **doc-release-branch** into docs-latest. +* Push **docs-latest** which starts the publishing process to clouddocs.f5.com. +* Checkout each of the LTS doc branches and push the changes to the **versions.json** files. +* Merge **docs-latest** back into **develop**. diff --git a/docs/api-documentation.rst b/docs/api-documentation.rst new file mode 100644 index 00000000..7e217f10 --- /dev/null +++ b/docs/api-documentation.rst @@ -0,0 +1,14 @@ + +.. _apidocs: + +OpenAPI Reference +================= + +To see the API reference in a new browser window, click |api|. + +| + + +.. |api| raw:: html + + API documentation \ No newline at end of file diff --git a/docs/apidocs.rst b/docs/apidocs.rst new file mode 100644 index 00000000..fef7cdb7 --- /dev/null +++ b/docs/apidocs.rst @@ -0,0 +1,6 @@ +.. _apidocumentation: + +API Reference +============= + +Internal reference, this is overwritten. \ No newline at end of file diff --git a/docs/authentication.rst b/docs/authentication.rst index 71d28010..f3ccd0a5 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -1,12 +1,12 @@ Authentication and Authorization -------------------------------- -Authorization to invoke Declarative Onboarding includes authorization to GET declarations stored in -Declarative Onboarding. +Authorization to invoke BIG-IP Declarative Onboarding includes authorization to GET declarations stored in +BIG-IP Declarative Onboarding. -Declarative Onboarding does not require its own credentials, however you must have administrator credentials for the BIG-IP that is running Declarative Onboarding. +BIG-IP Declarative Onboarding does not require its own credentials, however you must have administrator credentials for the BIG-IP that is running BIG-IP Declarative Onboarding. -Because Declarative Onboarding is an iControl LX extension, you can authenticate by including one of the following **header** values in your HTTP requests. +Because BIG-IP Declarative Onboarding is an iControl LX extension, you can authenticate by including one of the following **header** values in your HTTP requests. Basic Auth ~~~~~~~~~~ diff --git a/docs/big-iq-licensing.rst b/docs/big-iq-licensing.rst index 2c3a495e..761a1a85 100644 --- a/docs/big-iq-licensing.rst +++ b/docs/big-iq-licensing.rst @@ -3,7 +3,7 @@ Composing a declaration for licensing BIG-IP with a BIG-IQ ========================================================== -If you have an existing BIG-IQ device with a pool of F5 licenses (BIG-IQ License Manager), you can reference it from your Declarative Onboarding declaration in order to license your BIG-IP device. +If you have an existing BIG-IQ device with a pool of F5 licenses (BIG-IQ License Manager), you can reference it from your BIG-IP Declarative Onboarding declaration in order to license your BIG-IP device. To use this feature: @@ -11,11 +11,11 @@ To use this feature: - The license pool can only be a Registration Key pool, Purchased Pool, or a Utility (subscription/ELA) pool. See the |bigiq| documentation for more detailed information on License pool types. - In the BIG-IQ UI, you must include a targetUsername and targetPassphrase. BIG-IQ is able to pass a target token through the API, but the BIG-IQ **must** also have the target username and passphrase in the body so the BIG-IQ can discover and import the BIG-IP device after the onboarding process. -Additionally, see :doc:`json-pointers` for information on using JSON/Declarative Onboarding pointers in your declaration. +Additionally, see :doc:`json-pointers` for information on using JSON/BIG-IP Declarative Onboarding pointers in your declaration. -See :doc:`bigiq-examples` for additional example declarations. +See :ref:`BIG-IQ examples` for additional example declarations. -.. NOTE:: See |compat| for information on BIG-IQ and Declarative Onboarding compatibility. +.. NOTE:: See |compat| for information on BIG-IQ and BIG-IP Declarative Onboarding compatibility. Declaration class licensing with BIG-IQ @@ -24,7 +24,10 @@ Declaration class licensing with BIG-IQ In this declaration snippet, we only include the License class, which is specific to using the BIG-IQ to license your BIG-IP system. For a complete declaration, you could add the License class to the example in :doc:`composing-a-declaration` to configure DNS, NTP, VLANs, Routes and more. For the full BIG-IQ Licensing example declaration, see :ref:`bigiq1` and :ref:`bigiq2`. -In the following snippet, we set *reachable* to **true** (reachable means the BIG-IQ has a route to the BIG-IP), therefore we include a BIG-IP username and password. We are also using a utility pool behind the scenes on BIG-IQ, so use SKU keywords and unit of measure. If reachable is false, you only specify the hypervisor (see the :doc:`bigiq-examples` for example declarations). And for a RegKey pool, you do not need the SKU keywords or the unit of measure (see the table and :ref:`bigiq2` for usage). +In the following snippet, we set *reachable* to **true** (reachable means the BIG-IQ has a route to the BIG-IP), therefore we include a BIG-IP username and password. We are also using a utility pool behind the scenes on BIG-IQ, so use SKU keywords and unit of measure. If reachable is false, you only specify the hypervisor (see the :ref:`BIG-IQ examples` for example declarations). And for a RegKey pool, you do not need the SKU keywords or the unit of measure (see the table and :ref:`bigiq2` for usage). + +.. TIP:: There may be additional properties available. Be sure to see the :doc:`schema-reference` and :doc:`examples` for detailed information on each class and their associated properties. + .. code-block:: javascript :linenos: @@ -41,7 +44,7 @@ In the following snippet, we set *reachable* to **true** (reachable means the BI "unitOfMeasure": "hourly", "reachable": true, "bigIpUsername": "admin", - "bigIpPassword": "barbar" + "bigIpPassword": "asdfjkl" }, @@ -93,7 +96,7 @@ The License class contains information about your BIG-IQ device. For BIG-IQ, th Again, for the full BIG-IQ Licensing example declaration, see :ref:`bigiq1` and :ref:`bigiq2`. -See :doc:`bigiq-examples` for additional example declarations. +See :ref:`BIG-IQ examples` for additional example declarations. | @@ -101,12 +104,12 @@ See :doc:`bigiq-examples` for additional example declarations. .. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - The ability to revoke a license using Declarative Onboarding is available in version 1.3.0 and later. + The ability to revoke a license using BIG-IP Declarative Onboarding is available in version 1.3.0 and later. Revoking a license from a BIG-IP with BIG-IQ ============================================ -If you are using Declarative Onboarding 1.3.0 or later, you can use a declaration to revoke a license from a BIG-IP VE that was issued from a BIG-IQ license pool, and optionally relicense the BIG-IP VE with a new license. +If you are using BIG-IP Declarative Onboarding 1.3.0 or later, you can use a declaration to revoke a license from a BIG-IP VE that was issued from a BIG-IQ license pool, and optionally relicense the BIG-IP VE with a new license. .. IMPORTANT:: If the BIG-IP is not reachable from the BIG-IQ ("reachable": false), you must use **overwrite** if you want to relicense a BIG-IP VE (as the BIG-IP will not know the license was revoked). @@ -117,7 +120,7 @@ Revoking a license without relicensing -------------------------------------- If you want to revoke a license from a BIG-IP and not supply a new license, you simply add the **revokeFrom** property with name of the license pool to the license class. For example ``"revokeFrom": "myPool"``. -So the entire license class might look like the following: +So the entire license class might look like the following, which revokes the license from the BIG-IP VE, and leaves it in an unlicensed state. .. code-block:: javascript :emphasize-lines: 7 @@ -132,7 +135,6 @@ So the entire license class might look like the following: "reachable": false }, -This revokes the license from the BIG-IP VE, and leaves it in an unlicensed state. Revoking a license and relicensing a BIG-IP from a different license pool ------------------------------------------------------------------------- @@ -143,7 +145,7 @@ Relicensing a BIG-IP (with route) If you want to relicense a BIG-IP VE that is reachable from the BIG-IQ device, in your *reachable* declaration you simply add the **revokeFrom** property with name of the license pool you want to revoke the license from (for example ``"revokeFrom": "myPool"``). In the licensePool property, use the new license pool from which you want to give the BIG-IP a license. -So the entire license class might look like the following: +So the entire license class might look like the following, which revokes the license from the BIG-IP VE from the **myPool** license pool and relicenses it using the **myOtherPool** license pool: .. code-block:: javascript :emphasize-lines: 7-8 @@ -161,18 +163,23 @@ So the entire license class might look like the following: "unitOfMeasure": "hourly", "reachable": true, "bigIpUsername": "admin", - "bigIpPassword": "barbar" + "bigIpPassword": "asdfjkl" }, -This revokes the license from the BIG-IP VE from the **myPool** license pool and relicenses it using the **myOtherPool** license pool. + Relicensing a BIG-IP (no route) ``````````````````````````````` If you want to relicense a BIG-IP VE that is **unreachable** from the BIG-IQ device, in your *unreachable* declaration you must also use the **overwrite** property (``"overwrite": true``) in addition to the **revokeFrom** property with name of the license pool you want to revoke the license from (for example ``"revokeFrom": "myPool"``). In the licensePool property, use the new license pool from which you want to give the BIG-IP a license. +**New in BIG-IP DO 1.15** |br| +BIG-IP DO 1.15 adds the **tenant** property to the License class. This property allows you to specify an optional description for the license. This feature is useful in autoscale solutions managed by a BIG-IQ. The BIG-IP DO tenant property is prepended to the BIG-IQ tenant property. The BIG-IQ tenant property is *management address,hostname* by default, so when using the BIG-IP DO property, it becomes *BIG-IP DO-tenant-property,management-address,hostname*. This feature is only supported when **reachable** is **false**. + +.. IMPORTANT:: The following declaration snippet has been updated to include the new Tenant property introduced in BIG-IP DO 1.15. If you attempt to use it on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **tenant** property at the bottom. -So the entire license class might look like the following: + +So the entire license class might look like the following, which revokes the license from the BIG-IP VE from the **myPool** license pool and relicenses it using the **myOtherPool** license pool (while telling the BIG-IP VE to overwrite the existing license). .. code-block:: javascript :emphasize-lines: 6-7, 14 @@ -190,16 +197,21 @@ So the entire license class might look like the following: "unitOfMeasure": "hourly", "reachable": false, "hypervisor": "vmware", - "overwrite": true + "overwrite": true, + "tenant": "Optional custom descriptor" }, -This revokes the license from the BIG-IP VE from the **myPool** license pool and relicenses it using the **myOtherPool** license pool (while telling the BIG-IP VE to overwrite the existing license). Relicensing a BIG-IP (no route) using a different BIG-IQ device ``````````````````````````````````````````````````````````````` This section shows how to relicense a BIG-IP VE that is **unreachable**, AND you are using a different BIG-IQ device than the one you used to initially license the BIG-IP device. In this case, you also use the **revokeFrom** property, but you supply information about the BIG-IQ device you used to license the BIG-IP. You must also use the **overwrite** property (``"overwrite": true``) in addition to the **revokeFrom** property. +**New in BIG-IP DO 1.15** |br| +BIG-IP DO 1.15 adds the **tenant** property to the License class. This property allows you to specify an optional description for the license. This feature is useful in autoscale solutions managed by a BIG-IQ. The BIG-IP DO tenant property is prepended to the BIG-IQ tenant property. The BIG-IQ tenant property is *management address,hostname* by default, so when using the BIG-IP DO property, it becomes *BIG-IP DO-tenant-property,management-address,hostname*. This feature is only supported when **reachable** is **false**. + +.. IMPORTANT:: The following declaration snippet has been updated to include the new Tenant property introduced in BIG-IP DO 1.15. If you attempt to use it on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **tenant** property at the bottom. + For example, to revoke a license issued from the BIG-IQ at 10.0.2.200 and re-license with a license from the BIG-IQ at 10.0.1.200, the entire license class might look like the following: .. code-block:: javascript @@ -215,7 +227,7 @@ For example, to revoke a license issued from the BIG-IQ at 10.0.2.200 and re-lic "revokeFrom": { "bigIqHost": "10.0.2.200", "bigIqUsername": "admin", - "bigIqPassword": "barbar", + "bigIqPassword": "asdfjkl", "licensePool": "myPool", "reachable": false }, @@ -224,7 +236,8 @@ For example, to revoke a license issued from the BIG-IQ at 10.0.2.200 and re-lic "unitOfMeasure": "hourly", "reachable": false, "hypervisor": "vmware", - "overwrite": true + "overwrite": true, + "tenant": "Optional custom descriptor" }, This revokes the license from the BIG-IP VE from the **myPool** license pool from the initial BIG-IQ device, and relicenses it using the **myPool** license pool on the new BIG-IQ device on which you are composing this declaration (while telling the BIG-IP VE to overwrite the existing license). diff --git a/docs/bigip-examples.rst b/docs/bigip-examples.rst deleted file mode 100644 index 2b7e6be8..00000000 --- a/docs/bigip-examples.rst +++ /dev/null @@ -1,665 +0,0 @@ -.. _bigipexamples: - -BIG-IP and general example declarations ---------------------------------------- -The following are example declarations for BIG-IP, with some general examples that could also be used with BIG-IQ and the container. - - -1: Standalone declaration -^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example declaration that onboards a standalone BIG-IP system. See :doc:`composing-a-declaration` for specific details on this example. - -.. literalinclude:: ../examples/onboard.json - :language: json - - -:ref:`Back to top` - -| - - -.. _example2: - -2: Clustered declaration -^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example declaration that onboards a clustered BIG-IP system. See :doc:`clustering` for specific details on this example. - -.. literalinclude:: ../examples/onboardFailover.json - :language: json - -:ref:`Back to top` - -| - -.. _example6: - -3: Using JSON Pointers -^^^^^^^^^^^^^^^^^^^^^^ -The following is another example using a declaration for use in a container, but in this case, it also contains a number of examples of using JSON pointers in a declaration. For more information on JSON pointers, see :doc:`json-pointers`. - -.. literalinclude:: ../examples/licenseViaBigIqReachableASG.json - :language: json - - -:ref:`Back to top` - -| - -.. _avrstream: - - -4: Creating an Analytics profile to enable AVR data streaming -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for the Analytics profile is available in Declarative Onboarding v1.5.0 and later. - -In this example, we are licensing a new BIG-IP, provisioning AVR, and creating an Analytics profile (you must have AVR provisioned to create an Analytics profile). This allows you to stream AVR data for consumption by F5 Telemetry Steaming or similar applications. - -.. literalinclude:: ../examples/avrStreamingSupport.json - :language: json - :emphasize-lines: 17, 19-29 - - -:ref:`Back to top` - -| - -.. _keys: - -5: Adding public SSH keys to a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The **keys** property of the User class is available in DO v1.5.0 and later. - -In this example, we are adding public SSH keys to the root user and a guestUser. This can provide a higher level of security and easier automation. - -**Important notes about using the keys property** - -- Only the root user's master key (noted by the ``Host Processor Superuser``), in authorized_keys will be preserved. All other keys configured prior to running this declaration, WILL BE DELETED. -- If the **keys** field is left empty it will default to an empty array. This means leaving it empty will clear the authorized_keys file, except for the root's master key. -- For non-root users, the path to the authorized_keys is **/home/{username}/.ssh/authorized_keys**. -- For root, the path is **/root/.ssh/authorized_keys**. -- DO will set the non-root user's .ssh directory permissions to 700, with the authorized_keys permissions set to 600. - -.. literalinclude:: ../examples/publicKeys.json - :language: json - :emphasize-lines: 13-16, 27-30 - - -:ref:`Back to top` - -| - -.. _rdomain: - -6: Adding Route Domains to a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The **routeDomain** class is available in DO v1.6.0 and later. - -In this example, we show how to use a Route Domain in a declaration. A route domain is a configuration object that isolates network traffic for a particular application on the network. For more information on Route Domains, see |rddoc|. - -In the following declaration, we include a VLAN to show how to reference a VLAN that is being created. The SelfIp and the Route both show using the RouteDomain with **%100**, which is the **id** of the RouteDomain. - - - -.. literalinclude:: ../examples/routeDomains.json - :language: json - :emphasize-lines: 21, 25, 28-46 - - -:ref:`Back to top` - -| - -.. _dag: - -7: Setting the DAG IPv6 prefix length -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The **DagGlobals** class is available in DO v1.7.0 and later. - -In this example, we show how to use the DagGlobals class to set or modify the DAG global IPv6 prefix length. DAG Globals contain the global disaggregation settings; see the |dagdoc| documentation for more information. - -In the following declaration snippet, we show only the DagGlobals class. You can use this class as a part of a larger Declarative Onboarding declaration. - - - -.. literalinclude:: ../examples/dagGlobals.json - :language: json - - - -:ref:`Back to top` - -| - -.. _snmp: - -8: Configuring SNMP in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The ability to configure SNMP in a declaration is available in DO v1.7.0 and later. - -In this example, we show how to configure SNMP in a Declarative Onboarding declaration. You can use DO to configure SNMP agents, users, communities, trap events, and trap destinations. See the |snmpdoc| in the BIG-IP documentation for specific information. - -In the following declaration snippet we show only the classes related to SNMP. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/snmp.json - :language: json - -:ref:`Back to top` - -| - -.. _authmethods: - -9: Configuring BIG-IP authentication methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The ability to enable SSL for LDAP is available in DO 1.13 and later - -In this example, we show how to configure RADIUS, LDAP, and TACACS authentication in a Declarative Onboarding declaration using the **Authentication** class. The authentication class can (but does not have to) contain multiple authentication method subclasses but only one can be enabled at a time using the **enableSourceType** property (which matches the BIG-IP UI behavior). - -This example declaration contains all three authentication methods with the **enableSourceType** property set to **radius**. It also includes the SSL options for LDAP introduced in DO 1.13. - -For more information on options and DO usage, see |auth| and the subsequent entries in the Schema Reference. - -In the following declaration snippet we show only the classes related to authentication. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/authMethods.json - :language: json - -:ref:`Back to top` - -| - -.. _remoterole: - -10: Configuring Remote Roles for authentication -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The ability to configure remote roles for authentication is available in DO v1.7.0 and later. - -In this example, we show how to configure a remote role for authentication using the **RemoteAuthRole** class. See |loref| in the Schema reference for a description of each of the parameters for this class. - -**Important**: The BIG-IP only allows one role per user for each partition/tenant. Because some remote servers allow multiple user roles, the BIG-IP uses the **lineOrder** parameter to choose one of the conflicting roles for the user at login time. In these cases, the system chooses the role with the lowest line-order number. See |lineorder| in the BIG-IP documentation for more information and examples. - -In the following declaration snippet we show only the classes related to remote auth roles. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/remoteRoles.json - :language: json - -:ref:`Back to top` - -| - -.. _trafcontrol: - -11: Configuring Traffic Control properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for configuring all LTM global traffic control properties is available in DO v1.7.0 and later. - -In this example, we show how you can configure BIG-IP LTM global traffic control settings (ltm global-settings traffic-control) using a Declarative Onboarding declaration. For descriptions and usage details on these properties, see |tcref| in the Schema Reference. - -In the following declaration snippet we show only the classes related to Traffic Control. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/trafficControl.json - :language: json - -:ref:`Back to top` - -| - -.. _syslogdest: - -12: Configuring a System Log (syslog) Destination in declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The ability to configure a syslog destination is available in DO v1.7.0 and later. - -In this example, we show how to configure a syslog destination using the **SyslogRemoteServer** class. For information on syslog destinations, see |sldocs| and the |slkb| Knowledge Base article. Also see |slref| in the Schema reference for usage options. - -**Important**: The remote syslog server must be accessible from your BIG-IP system on the default route domain (Domain 0) or management network, and conversely, your BIG-IP system is accessible from the remote syslog server. - -In the following declaration snippet we show only the SyslogRemoteServer class. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/syslogDestination.json - :language: json - -:ref:`Back to top` - -| - -.. _cmphash: - -13: Using the CMP Hash property in a VLAN -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The VLAN property **cmp-hash** is available in DO v1.7.0 and later. - -Starting in 1.7.0, you have the option of using the **cmp-hash** property on a VLAN. The CMP Hash setting allows all connections from a client system to use the same set of TMMs, improving system performance. For more information, see |cmpdocs| in the BIG-IP documentation. You can also see |cmpref| in the Schema Reference for usage options. - -In the following declaration snippet we show only the VLAN class with cmp-hash using Source Address as the traffic disaggregation method. You can use this class as a part of a larger Declarative Onboarding declaration. - -.. literalinclude:: ../examples/vlanCmpHash.json - :language: json - -:ref:`Back to top` - -| - -.. _sshex: - -14: Configuring SSHD settings in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for configuring SSHD settings is available in DO v1.8.0 and later. - -In this example, we show how you can configure SSHD (SSH daemon) settings in a Declarative Onboarding declaration. For usage and options, see |sshd| in the Schema Reference. - -In the following declaration, we show only the SSHD class. You can use this class as a part of a larger Declarative Onboarding declaration. - - -.. literalinclude:: ../examples/sshd.json - :language: json - -:ref:`Back to top` - -| - -.. _httpdex: - -15: Configuring HTTPD settings in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for configuring HTTPD settings is available in DO v1.8 and later. - -In this example, we show how you can configure HTTPD (HTTP daemon) settings in a Declarative Onboarding declaration. For usage and options, see |httpd| in the Schema Reference. - -.. NOTE:: If you use the BIG-IP Configuration utility, we recommend you exit the utility before changes are made to the system using the HTTPD component. Making changes to the system using this component causes a restart of the httpd daemon, and restarting the httpd daemon requires a restart of the Configuration utility. - -In the following declaration, we show only the HTTPD class. You can use this class as a part of a larger Declarative Onboarding declaration. - - -.. literalinclude:: ../examples/httpd.json - :language: json - -:ref:`Back to top` - -| - -.. _systemex: - -16: Configuring System settings in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for disabling the auto-check feature is available in DO v1.13 and later. - -In this example, we show how you can configure some System settings in a Declarative Onboarding declaration. This enables you to set auto-timeout values for serial console (CLI) and TMSH interactive mode sessions, as well as set a hostname, if you have not set one in the Common class. - -.. IMPORTANT:: If you set a hostname in the Common class, you cannot use the hostname property in the System class; they are mutually exclusive. - -For usage and options, see |sysclass| in the Schema Reference. - -DO 1.13 introduced the ability to disable the automatic update check feature. The autoCheck property controls whether the BIG-IP checks for and recommends software updates. See |k15000| for more information. - -In the following declaration, we show only the System class (including autoCheck introduced in 1.13). You can use this class as a part of a larger Declarative Onboarding declaration. - -**Important**: If you try to use this declaration with a DO version prior to 1.13, it will fail. Either upgrade to 1.13, or remove the autoCheck line. - - -.. literalinclude:: ../examples/system.json - :language: json - -:ref:`Back to top` - -| - -.. _example17: - -17: Clustered declaration with IP addresses for Device Group owner and members -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for using IP addresses for Device Group owners and members is available in DO v1.11 and later. - -The following is an example declaration that onboards a clustered BIG-IP system, but shows how you can use an IP address for the Device Group members and owner. - -See :ref:`devicegroup` for more information. - -.. literalinclude:: ../examples/clusterWithIpAddresses.json - :language: json - -:ref:`Back to top` - -| - -.. _example18: - -18: Updating the TLS/SSL Device Certificate in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for including a TLS/SSL device certificate and key is available in DO v1.12 and later. - -This example declaration shows how you can create/upload a device certificate in a Declarative Onboarding declaration. The BIG-IP system uses the device certificate to authenticate access to the Configuration utility and to accommodate device-to-device communication processes, such as configuration synchronization. - -For more information and how this process works manually, see the KB article |certdoc|. - -A couple of things to note when including certificates and keys in a declaration: - -- DO always writes to **/config/httpd/conf/ssl.crt/server.crt** and **ssl.key/server.key** -- If the device certificate is updated (that is, if the certificate in the declaration does not match the certificate in those directories), DO reboots the BIG-IP device in order to include the updated certificate -- DO makes backups of the certificates and keys in those directories before overwriting the existing certificate and key -- Like other settings in DO, if a subsequent declaration is posted without the certificate, DO will restore the certificate that was there when it first ran. - -See |certclass| in the schema reference for more information and usage. - -.. literalinclude:: ../examples/deviceCertificate.json - :language: json - -:ref:`Back to top` - -| - -.. _example19: - -19: Using the userAgent Controls property -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for **userAgent** is available in DO v1.13 and later - -In this example, we show how you can use the **userAgent** property in the new **Controls** class. The userAgent property allows you to set a unique identifier in usage data. - -This declaration includes the Controls class with userAgent set to **BIG-IQ/7.1 Configured by API**. - -See |controls| in the Schema Reference for more information. - - -.. literalinclude:: ../examples/userAgent.json - :language: json - -:ref:`Back to top` - -| - -.. _example20: - -20: Configuring Audit Logging in a declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for configuring audit logging is available in DO v1.13 and later - -In this example, we show how you can configure audit logging in the System class of a Declarative Onboarding declaration. This allows audit logging to start as early as possible. - -See |sysclass| in the Schema Reference for DO usage and options. For detailed information about audit logging on the BIG-IP, see the |auditlog|. - -.. IMPORTANT:: **guiAuditLog** is only available on TMOS v14.0 and later - - -.. literalinclude:: ../examples/auditLogging.json - :language: json - -:ref:`Back to top` - -| - -.. _example21: - -21: Configuring MAC Masquerading on Traffic Groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for MAC Masquerade on Traffic Groups is available in DO v1.13 and later - -In this example, we show how you can configure MAC Masquerading on Traffic Groups. This is a part of the new **MAC_Masquerade** class. - -For detailed information about Mac Masquerade on the BIG-IP, see |mmkb|. - -See |macm| in the Schema Reference for DO usage and options. - - -.. literalinclude:: ../examples/macMasquerade.json - :language: json - -:ref:`Back to top` - -| - -.. _example22: - -22: Configuring VLAN Failsafe -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for VLAN Failsafe is available in DO v1.14 and later - -In this example, we show how you can configure VLAN Failsafe settings in a Declarative Onboarding declaration. This is a part of the |cmpref|, and includes the new properties **failsafeEnabled**, **failsafeAction**, and **failsafeTimeout**. - -For detailed information about VLAN Failsafe on the BIG-IP, see |vlanfs|. - -See |cmpref| in the Schema Reference for DO usage and options. - - -.. literalinclude:: ../examples/vlanFailsafe.json - :language: json - - -:ref:`Back to top` - -| - -.. _example23: - -23: Configuring a DNS Resolver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for DNS Resolvers is available in DO v1.14 and later - -In this example, we show how you create a DNS Resolver in a Declarative Onboarding declaration using the |dnsresolver| class introduced in DO 1.14. The DNS Resolver is the internal DNS resolver the BIG-IP system uses to fetch the internal proxy response. - -See |dnsresolver| in the Schema Reference for DO usage and options. - -For detailed information about the DNS Resolver, see |dnsdoc| on AskF5. - - -.. literalinclude:: ../examples/dnsResolver.json - :language: json - -| - -.. _example24: - -24: Configuring a TCP Forward Tunnel -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for TCP Forward Tunnels is available in DO v1.14 and later - -In this example, we show how you create a TCP Forward Network Tunnel in a Declarative Onboarding declaration using the |tunnel| class introduced in DO 1.14. - -Currently, **tcp_forward** is the only profile (**tunnelType**) Declarative Onboarding supports. The tcp_forward profile specifies a tunnel used for forward proxy connections. - -See |tunnel| in the Schema Reference for DO usage and options. - - -.. literalinclude:: ../examples/tcpForwardTunnel.json - :language: json - -:ref:`Back to top` - -| - -.. _example25: - -25: Configuring Traffic Groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - Support for Traffic Groups is available in DO v1.14 and later - -This example shows how to create Traffic Groups using Declarative Onboarding 1.14 and later. A traffic group is a group of configuration objects on a BIG-IP which is able to float to another device in a device group in case of failure. For more information, see :ref:`trafficgroup` on the Clustering page, and |tgdoc|. - -See |tg| in the Schema Reference for DO usage and options. - -.. IMPORTANT:: The HA Score failover method is not currently supported. DO uses the HA Order failover method. |br| |br| Because DO uses HA Order for failover, the declaration must include a hostname, located inside of a deviceGroup. In the following example, the declaration defines a Device Group with a host name. See :ref:`devicegroup` for information on Device Groups. - - -.. literalinclude:: ../examples/trafficGroups.json - :language: json - -:ref:`Back to top` - - -.. |br| raw:: html - -
- -.. |rddoc| raw:: html - - Route Domain documentation - -.. |dagdoc| raw:: html - - Disaggregation DAG modes - -.. |snmpdoc| raw:: html - - Monitoring BIG-IP System Traffic with SNMP - -.. |tcref| raw:: html - - TrafficControl Class - -.. |loref| raw:: html - - RemoteAuthRole Class - - -.. |rolesdoc| raw:: html - - Remote User Account Management - -.. |lineorder| raw:: html - - Line Order - -.. |sldocs| raw:: html - - External Monitoring - -.. |slkb| raw:: html - - Configuring remote logging - -.. |slref| raw:: html - - SyslogRemoteServer Class - -.. |cmpdocs| raw:: html - - Additional VLAN Configuration Options - -.. |cmpref| raw:: html - - VLAN Class - -.. |trunkdoc| raw:: html - - Trunk documentation - -.. |trunkref| raw:: html - - Trunk class - -.. |sshd| raw:: html - - SSHD - -.. |httpd| raw:: html - - HTTPD - -.. |sysclass| raw:: html - - System - -.. |certclass| raw:: html - - DeviceCertificate - -.. |certdoc| raw:: html - - Updating a self-signed SSL device certificate on a BIG-IP system - -.. |controls| raw:: html - - Device_Controls - -.. |auth| raw:: html - - Authentication - -.. |k15000| raw:: html - - K15000 - -.. |auditlog| raw:: html - - Audit Logging documentation - -.. |macm| raw:: html - - Mac_Masquerade - -.. |mmkb| raw:: html - - K13502: Configuring MAC masquerade - -.. |vlanfs| raw:: html - - K13297: Overview of VLAN failsafe - -.. |dnsresolver| raw:: html - - DNS_Resolver - - -.. |dnsdoc| raw:: html - - BIG-IP DNS documentation - -.. |tunnel| raw:: html - - Tunnel - -.. |tg| raw:: html - - TrafficGroup - -.. |tgdoc| raw:: html - - BIG-IP Device Service Clustering: Administration - -.. |hagroup| raw:: html - - BIG-IP documentation - diff --git a/docs/bigiq-examples.rst b/docs/bigiq-examples.rst deleted file mode 100644 index 16a8add7..00000000 --- a/docs/bigiq-examples.rst +++ /dev/null @@ -1,207 +0,0 @@ -.. _iqexamples: - -BIG-IQ example declarations ---------------------------- - -The following are example declarations for licensing with BIG-IQ. See :doc:`big-iq-licensing` for detailed information about composing declarations with BIG-IQ. - -See the |bigiq| documentation for more detailed information on License pool types. See |compat| for information on BIG-IQ and Declarative Onboarding compatibility - - - - -.. _bigiq1: - -1: Licensing with BIG-IQ: Regkey Pool - Route to BIG-IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example of using a BIG-IQ to license your BIG-IP systems, where the BIG-IQ has an existing route to the BIG-IP. In this example, our existing BIG-IQ license pool is a RegKey pool that contains BIG-IP VE RegKeys. Because the BIG-IP VE is reachable (has a route to the BIG-IQ), we also specify the BIG-IP user name and password. - -.. NOTE:: Currently, to use a RegKey pool the BIG-IP must be reachable from the BIG-IQ. - -The entire *License* class is unique to using BIG-IQ for licensing, so the items specific to RegKey pools are highlighted. - -.. literalinclude:: ../examples/licenseViaBigIqRegKeyPool.json - :language: json - :emphasize-lines: 15-17 - -:ref:`Back to top` - -| - -.. _bigiq2: - -2: Licensing with BIG-IQ: Utility Pool - Route to BIG-IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In this example, our BIG-IQ license pool is a utility (subscription) pool. Utility pools contain licenses for BIG-IP services you grant for a specific unit of measure (hourly, daily, monthly, or yearly). - -Utility pools include a additional parameters: **skuKeyword1** and **skuKeyword2**, and **unitOfMeasure** (see :ref:`license-pool` for details). - -We've highlighted the lines that are specific to this utility and Route example (reachable=true). - -.. literalinclude:: ../examples/licenseViaBigIqUtilityReachable.json - :language: json - :emphasize-lines: 16-21 - -:ref:`Back to top` - -| - -.. _bigiq3: - -3: Licensing with BIG-IQ: Utility Pool - No Route to BIG-IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is another example of using a BIG-IQ to license your BIG-IP systems with a utility pool. However, in this case the BIG-IQ does **not** have an existing route to the BIG-IP. - -For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). - -In this example, we've highlighted the lines that are specific to this utility and No Route example (reachable=false). See :doc:`big-iq-licensing` for specific details on this example. - -.. literalinclude:: ../examples/licenseViaBigIqUtilityUnreachable.json - :language: json - :emphasize-lines: 16-20 - -:ref:`Back to top` - -| - -.. _bigiq4: - -4: Licensing with BIG-IQ: Purchased Pool - Route to BIG-IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In this example, our BIG-IQ license pool is a Purchased pool. A Purchased pool is a prepaid pool of a specific number of concurrent license grants for a single BIG-IP service, such as LTM. - -Because the BIG-IP VE is reachable (has a route to the BIG-IQ), we also specify the BIG-IP user name and password. - -.. literalinclude:: ../examples/licenseViaBigIqPurchasedPoolReachable.json - :language: json - :emphasize-lines: 16-18 - -:ref:`Back to top` - -| - -.. _bigiq5: - -5: Licensing with BIG-IQ: Purchased Pool - No Route to BIG-IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This example also uses a Purchased pool, but without a route to the BIG-IP. - -For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). - -.. literalinclude:: ../examples/licenseViaBigIqPurchasedPoolUnreachable.json - :language: json - :emphasize-lines: 16-17 - -:ref:`Back to top` - -| - - - -.. _revoke: - - -6: Revoking a BIG-IP license from BIG-IQ without relicensing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example of using BIG-IQ to revoke a license from an unreachable BIG-IP VE using **revokeFrom** and specifying the license pool. In this example, we are only revoking the license, and not relicensing the BIG-IP VE. See See :ref:`Revoking a license using BIG-IQ` for specific details on this example. - -.. literalinclude:: ../examples/revokeViaBigIqUnreachable.json - :language: json - :emphasize-lines: 14 - - -:ref:`Back to top` - -| - -.. _relicense: - - -7: Revoking and relicensing a BIG-IP (with route) from BIG-IQ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example of using BIG-IQ to revoke a license and then relicense a reachable BIG-IP VE. In this example, we are both revoking the initial license and relicensing the BIG-IP VE from a different license pool on the BIG-IQ. The line with the new licensing pool and the revoke line are highlighted. See See :ref:`Revoking a license using BIG-IQ` for specific details on this example. - -.. literalinclude:: ../examples/reLicenseViaBigIqReachable.json - :language: json - :emphasize-lines: 14-15 - - -:ref:`Back to top` - -| - -.. _relicense-un: - - -8: Revoking and relicensing a BIG-IP (no route) from BIG-IQ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following is an example of using BIG-IQ to revoke a license and then relicense an unreachable BIG-IP VE. In this example, we are both revoking the initial license and relicensing the BIG-IP VE from a different license pool on the BIG-IQ. Additionally, because the BIG-IP device does not have a route to the BIG-IQ (unreachable), you must use **overwrite = true** to let the BIG-IP VE know the system is overwriting the license. - -For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). - -We have highlighted the new licensing pool, the revoke line, the hypervisor, and the overwrite line. See :ref:`Revoking a license using BIG-IQ` for specific details on this example. - -.. literalinclude:: ../examples/reLicenseViaBigIqUnreachable.json - :language: json - :emphasize-lines: 14-15, 20-21 - -:ref:`Back to top` - -| - -.. _relicense-new: - - -9: Revoking and relicensing a BIG-IP (no route) from a different BIG-IQ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This example is similar to example 9, however in this case, we are using a different BIG-IQ device to revoke and relicense the BIG-IP VE from an unreachable BIG-IP VE. In this case, we specify additional information in the *revokeFrom* property to reference the BIG-IQ that initially licensed the BIG-IP VE. Again, specifying the appropriate hypervisor is required. See :ref:`Revoking a license using BIG-IQ` for specific details on this example. - -.. literalinclude:: ../examples/reLicenseViaNewBigIqUnreachable.json - :language: json - :emphasize-lines: 15-21, 26-27 - - -:ref:`Back to top` - - -.. _bigiqdo1: - -9: Onboarding a BIG-IP in AWS via BIG-IQ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In this example, we onboard a BIG-IP VE in AWS using the DO endpoint on the BIG-IQ device. This example uses both targetHost to specify the BIG-IP information, and bigIqSettings. - -See :ref:`do-bigiq-table` for information on the bigIqSettings parameters. These parameters are highlighted in the following declaration. - -See the BIG-IQ API documentation for similar examples for |bigiqazure| and |bigiqvmware|. - -.. literalinclude:: ../examples/onboardViaBigIqAws.json - :language: json - :emphasize-lines: 49-59 - - -:ref:`Back to top` - - -.. |br| raw:: html - -
- -.. |bigiq| raw:: html - - BIG-IQ - -.. |compat| raw:: html - - K54909607 - - -.. |bigiqazure| raw:: html - - Microsoft Azure - -.. |bigiqvmware| raw:: html - - VMware Cloud \ No newline at end of file diff --git a/docs/clustering-managing-devices.rst b/docs/clustering-managing-devices.rst index 2ad906bb..973c5e4d 100644 --- a/docs/clustering-managing-devices.rst +++ b/docs/clustering-managing-devices.rst @@ -1,7 +1,7 @@ Adding or removing members of a Device Group ============================================ -This page describes how to handle the scenario in which one BIG-IP in Device Group goes down (goes offline, is deleted, gets corrupted, etc.), and how to use DO on a BIG-IP in the group that is still available to add a new BIG-IP instance to the group. It also applies if you want to simply add and/or remove a device from a cluster using Declarative Onboarding. +This page describes how to handle the scenario in which one BIG-IP in Device Group goes down (goes offline, is deleted, gets corrupted, etc.), and how to use BIG-IP DO on a BIG-IP system in the group that is still available to add a new BIG-IP instance to the group. It also applies if you want to simply add and/or remove a device from a cluster using BIG-IP Declarative Onboarding. In order to replace a device in a cluster, you must perform the following: diff --git a/docs/clustering.rst b/docs/clustering.rst index 7dade0ae..ab27dec6 100644 --- a/docs/clustering.rst +++ b/docs/clustering.rst @@ -1,16 +1,16 @@ .. _clustering: -Composing a Declarative Onboarding declaration for a cluster of BIG-IPs -======================================================================= +Composing a BIG-IP Declarative Onboarding declaration for a cluster of BIG-IPs +============================================================================== -Declarative Onboarding can also create a clustered configuration (Device Service Cluster) between two or more BIG-IP systems. You must install Declarative Onboarding and submit a declaration on each device in the cluster, and all BIG-IP devices must be on the same BIG-IP version. You specify one BIG-IP system as the 'owner' and the other BIG-IPs as 'members' (see :ref:`devicegroup`). +BIG-IP Declarative Onboarding can also create a clustered configuration (Device Service Cluster) between two or more BIG-IP systems. You must install BIG-IP Declarative Onboarding and submit a declaration on each device in the cluster, and all BIG-IP devices must be on the same BIG-IP version. You specify one BIG-IP system as the 'owner' and the other BIG-IPs as 'members' (see :ref:`devicegroup`). BIG-IP clustering is well-documented in the product documentation; for detailed information about clustering on the BIG-IP system, see |cluster|. .. TIP:: You can use GET to the URI ``https:///mgmt/shared/declarative-onboarding`` to track whether a declaration is successful or get information on why it failed. -Additionally, see :doc:`json-pointers` for information on using JSON/Declarative Onboarding pointers in your declaration. +Additionally, see :doc:`json-pointers` for information on using JSON/BIG-IP Declarative Onboarding pointers in your declaration. Declaration classes for a cluster of BIG-IPs @@ -18,6 +18,8 @@ Declaration classes for a cluster of BIG-IPs In this example, we include the classes that are specific to clustering. For a complete declaration, you could add the classes shown in :doc:`composing-a-declaration` to configure DNS, NTP, VLANs, Routes and more. For the full clustering example declaration, see :ref:`example2`. +.. NOTE:: Some classes are only available in certain versions of BIG-IP Declarative Onboarding. See the individual class sections for any version notices. + For some of the clustering components, like ConfigSync and failoverAddress, you can use JSON pointers to reference objects/properties in declarations. .. NOTE:: The DeviceTrust and DeviceGroup sections in both declarations should be identical. For DeviceTrust, if the remoteHost matches the management IP or one of the self IPs of the host on which it is running, that DeviceTrust section is ignored. If it does not match, then the device processing the declaration will send a request to the remote host to be added to trust. There is similar logic regarding the DeviceGroup owner. The owning device just creates the group, the other device requests to be added to the group. @@ -63,6 +65,11 @@ The following declaration snippet could continue after the :ref:`route-class` in "remoteHost": "/Common/failoverGroup/members/0", "remoteUsername": "admin", "remotePassword": "pass2word" + }, + "myMirror": { + "class": "MirrorIp", + "primaryIp": "10.1.0.20", + "secondaryIp": "any6" } @@ -74,13 +81,16 @@ If there is a default value, it is shown in bold in the Options column. Use the index in the left pane if you want to go directly to a particular section. +.. TIP:: There may be additional properties available in some of the classes. Be sure to see the :doc:`schema-reference` and :doc:`examples` for detailed information on each class and their associated properties. + + .. _sync-class: Configsync class ```````````````` The first class specific to clustering is the configsync class. This class contains the properties responsible for propagating BIG-IP configuration changes, including device trust information, to all devices in a device group. For more information on configsync on the BIG-IP, see |cs|. Because this example assumes we are using this class together with the standalone declaration, we can use a JSON pointer to the self IP address we defined. -.. NOTE:: As of DO 1.7.0, **none** is a valid value for configsyncIP. +.. NOTE:: As of BIG-IP DO 1.7.0, **none** is a valid value for configsyncIP. .. code-block:: javascript :linenos: @@ -150,7 +160,7 @@ For more information on Device Groups on the BIG-IP, see |group|. In this examp **Important**: You cannot use *autoSync* and *fullLoadOnSync* together. -.. NOTE:: In Declarative Onboarding v1.11.0 and later, the member and owner parameters can be IP addresses. See :ref:`Example 17` for an example declaration. +.. NOTE:: In BIG-IP Declarative Onboarding v1.11.0 and later, the member and owner parameters can be IP addresses. See :ref:`Example 17` for an example declaration. @@ -206,7 +216,7 @@ The next class specific to clustering is the traffic group class. A traffic grou For detailed information about Traffic Groups and clustering on the BIG-IP, see |tgdoc|. See :ref:`Traffic Groups` for an example declaration. -.. IMPORTANT:: The HA Score failover method is not currently supported. DO uses the HA Order failover method. |br| |br| Because DO uses HA Order for failover, the declaration must include a hostname, located inside of a deviceGroup. In the example, the declaration defines a Device Group with a host name. +.. IMPORTANT:: The HA Score failover method is not currently supported. BIG-IP DO uses the HA Order failover method. |br| |br| Because BIG-IP DO uses HA Order for failover, the declaration must include a hostname, located inside of a deviceGroup. In the example, the declaration defines a Device Group with a host name. .. code-block:: javascript @@ -226,21 +236,21 @@ For detailed information about Traffic Groups and clustering on the BIG-IP, see | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Parameter | Options | Required*? | Description/Notes | -+=====================+===================+=============+================================================================================================================================================================================================================================================================================================================================+ -| class | TrafficGroup | Yes | Indicates that this property contains Traffic Group configuration. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| autoFailbackEnabled | true, **false** | No | Specifies whether the traffic group fails back to the default device. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| autoFailbackTime | integer | No | Specifies the time required to fail back. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| failoverMethod | ha-order | No | Specifies the method to failover the traffic-group to another device. Currently only ha-order is supported, where a list of devices and their respective HA load is used to decide the next one to take over if the current devices fails. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| haLoadFactor | integer | No | Specifies a number for this traffic group that represents the load this traffic group presents to the system relative to other traffic groups. This allows the failover daemon to load balance the active traffic groups amongst the devices. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| haOrder | array | No | List of devices that specifies the order in which the devices will become active for the traffic group when a failure occurs. May contain from zero up to the number of devices in the failover device group. If autoFailbackEnabled is true, this list **must** contain at least one entry for the auto failback device. | -+---------------------+-------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Parameter | Options | Required*? | Description/Notes | ++=====================+===================+=============+====================================================================================================================================================================================================================================================+ +| class | TrafficGroup | Yes | Indicates that this property contains Traffic Group configuration. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| autoFailbackEnabled | true, **false** | No | Specifies whether the traffic group fails back to the default device. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| autoFailbackTime | integer | No | Specifies the time required to fail back. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| failoverMethod | ha-order | No | Specifies the method to failover the traffic-group to another device. Currently only ha-order is supported, where a list of devices and their respective HA load is used to decide the next one to take over if the current devices fails. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| haLoadFactor | integer | No | Specifies a number for this traffic group that represents the load this traffic group presents to the system relative to other traffic groups. This allows the failover daemon to load balance the active traffic groups amongst the devices. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| haOrder | array | No | List of devices that specifies the order in which the devices will become active for the traffic group when a failure occurs. May contain from zero up to the number of devices in the failover device group. | ++---------------------+-------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ \* The required column applies only if you are using this class. @@ -250,7 +260,7 @@ For detailed information about Traffic Groups and clustering on the BIG-IP, see Device Trust class `````````````````` -The final class specific to clustering is the device trust class. Device trust establishes trust relationships between BIG-IP devices on the network, through mutual certificate-based authentication. For more information on Device Trust on the BIG-IP, see |trust|. +The next class specific to clustering is the device trust class. Device trust establishes trust relationships between BIG-IP devices on the network, through mutual certificate-based authentication. For more information on Device Trust on the BIG-IP, see |trust|. .. code-block:: javascript :linenos: @@ -285,6 +295,40 @@ The final class specific to clustering is the device trust class. Device trust e \* The required column applies only if you are using this class. +.. _mirrorip: + +MirrorIp class +`````````````` +The next class specific to clustering is the MirrorIP class, introduced in BIG-IP DO v1.16. The MirrorIP class allows you to configure connection and persistence mirroring information in a BIG-IP Declarative Onboarding declaration. This allows you to configure clustered BIG-IPs to duplicate connection and persistence information to peer members of the BIG-IP device group, providing higher reliability but may affect system performance. + +For more information and BIG-IP DO usage, see |mirrorref|. See :ref:`example29` for an example declaration. + + +.. code-block:: javascript + :linenos: + + "myMirror": { + "class": "MirrorIp", + "primaryIp": "10.1.0.20", + "secondaryIp": "any6" + } + + +| + ++---------------------+-------------------+-------------+------------------------------------------------------------------------------------------------+ +| Parameter | Options | Required*? | Description/Notes | ++=====================+===================+=============+================================================================================================+ +| class | MirrorIp | Yes | Indicates that this property contains connection and persistence mirroring information. | ++---------------------+-------------------+-------------+------------------------------------------------------------------------------------------------+ +| primaryIp | string | No | IP address of the primary mirror. Specify **any6** to disable (the default is **any6**). | ++---------------------+-------------------+-------------+------------------------------------------------------------------------------------------------+ +| secondaryIp | string | No | IP address of the secondary mirror. Specify **any6** to disable (the default is **any6**). | ++---------------------+-------------------+-------------+------------------------------------------------------------------------------------------------+ + +\* The required column applies only if you are using this class. + + .. |cs| raw:: html Configsync documentation @@ -312,4 +356,8 @@ The final class specific to clustering is the device trust class. Device trust e .. |br| raw:: html -
\ No newline at end of file +
+ +.. |mirrorref| raw:: html + + MirrorIp \ No newline at end of file diff --git a/docs/components.rst b/docs/components.rst index 84f25ce1..bc3ef1fa 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -1,24 +1,24 @@ -Components of Declarative Onboarding ------------------------------------- +Components of BIG-IP Declarative Onboarding +------------------------------------------- -Declarative Onboarding Declaration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +BIG-IP Declarative Onboarding Declaration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A Declarative Onboarding declaration describes the desired initial configuration of an Application +A BIG-IP Declarative Onboarding declaration describes the desired initial configuration of an Application Delivery Controller (ADC) such as F5 BIG-IP. -Declarative Onboarding JSON Schema -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +BIG-IP Declarative Onboarding JSON Schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The |json| schema validates the declaration, and then produces a BIG-IP -configuration. The JSON Schema document prescribes the syntax of an Declarative Onboarding +configuration. The JSON Schema document prescribes the syntax of a BIG-IP Declarative Onboarding declaration. The declaration schema controls which objects may appear in a declaration, what name they may or must use, what properties they may have, which of those you must supply in the declaration, and -which Declarative Onboarding may fill with default values. The schema also specifies the ranges of +which BIG-IP Declarative Onboarding may fill with default values. The schema also specifies the ranges of values certain properties may take. -Declarative Onboarding contains two modules: a |rest| worker and an audit engine. The REST worker +BIG-IP Declarative Onboarding contains two modules: a |rest| worker and an audit engine. The REST worker provides a |crud| interface for creating and modifying the declaration document. The audit engine is responsible for aligning BIG-IP configuration with the declaration document. diff --git a/docs/composing-a-declaration.rst b/docs/composing-a-declaration.rst index 3a44dbb0..ed832c35 100644 --- a/docs/composing-a-declaration.rst +++ b/docs/composing-a-declaration.rst @@ -1,12 +1,12 @@ .. _composing: -Composing a Declarative Onboarding declaration for a standalone BIG-IP -====================================================================== +Composing a BIG-IP Declarative Onboarding declaration for a standalone BIG-IP +============================================================================= -The most important part of using Declarative Onboarding is creating a declaration that includes the BIG-IP objects you want the system to configure. +The most important part of using BIG-IP Declarative Onboarding is creating a declaration that includes the BIG-IP objects you want the system to configure. -To submit an Declarative Onboarding declaration, use a specialized RESTful API client such as Postman or a universal client such as cURL. +To submit a BIG-IP Declarative Onboarding declaration, use a specialized RESTful API client such as Postman or a universal client such as cURL. To transmit the declaration, you POST the declaration to the URI ``/mgmt/shared/declarative-onboarding``. If you are using a single NIC BIG-IP, include port 8443: ``:8443/mgmt/shared/declarative-onboarding`` @@ -14,11 +14,11 @@ To transmit the declaration, you POST the declaration to the URI ```_. -Additionally, see :doc:`json-pointers` for information on using JSON/Declarative Onboarding pointers in your declaration. +Additionally, see :doc:`json-pointers` for information on using JSON/BIG-IP Declarative Onboarding pointers in your declaration. -To see how to use BIG-IQ to license your BIG-IP VEs, see :doc:`big-iq-licensing`. If you want to use Declarative Onboarding in a Docker Container, see :doc:`do-container`. +To see how to use BIG-IQ to license your BIG-IP VEs, see :doc:`big-iq-licensing`. -.. IMPORTANT:: Domain name resolution is used anywhere the declaration accepts a hostname. DO makes sure that any hostnames are resolvable and fails if they are not. The exception is deviceGroup.members, which do not require hostname resolution as they have been added to the trust) +.. IMPORTANT:: Domain name resolution is used anywhere the declaration accepts a hostname. BIG-IP DO makes sure that any hostnames are resolvable and fails if they are not. The exception is deviceGroup.members, which do not require hostname resolution as they have been added to the trust) @@ -27,6 +27,8 @@ Sample declaration for a standalone BIG-IP In this section, we show an example of a standalone (non-clustered) declaration which configures some common system and networking components on the BIG-IP system. To see an example of the parts of a declaration that onboards a cluster of BIG-IPs, see :doc:`clustering`. +.. TIP:: There may be additional properties available in some of the classes. Be sure to see the :doc:`schema-reference` and :doc:`examples` for detailed information on each class and their associated properties. + This example is the entire declaration. The following sections break down each class of this example declaration. @@ -43,6 +45,8 @@ In this section, we break down the example into each class so you can understand If there is a default value, it is shown in bold in the Options column. +.. TIP:: There may be additional properties available in some of the classes. Be sure to see the :doc:`schema-reference` and :doc:`examples` for detailed information on each class and their associated properties. + Use the index in the left pane if you want to go directly to a particular class. .. _base-comps: @@ -61,39 +65,72 @@ For more information, see |deviceclass| in the Schema Reference. "schemaVersion": "1.0.0", "class": "Device", "async": true, - "label": "Basic onboarding", + "webhook": "https://example.com/myHook", + "label": "my BIG-IP declaration for declarative onboarding", | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ -| Parameter | Options | Required? | Description/Notes | -+====================+================================+============+====================================================================================================================================+ -| schemaVersion | string for version number | Yes | Version of Declarative Onboarding schema this declaration uses. | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ -| class | Device | Yes | Indicates this JSON document is a Device declaration. | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ -| async | true, **false** | No | If true, async tells the API to return a 202 HTTP status before processing is complete. You can then poll for status using GET. | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ -| webhook | string (URL) | No | DO v1.6.0 and later. You can optionally specify the URL for a webhook, to which DO sends the final response from the declaration. | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ -| label | string | No | Optional friendly label for this declaration. | -+--------------------+--------------------------------+------------+------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Parameter | Options | Required? | Description/Notes | ++====================+================================+============+======================================================================================================================================================================================================================================================================================+ +| schemaVersion | string for version number | Yes | Version of Declarative Onboarding schema this declaration uses. | ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| class | Device | Yes | Indicates this JSON document is a Device declaration. | ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| async | true, **false** | No | If true, async tells the API to return a 202 HTTP status before processing is complete. You can then poll for status using GET. | ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| webhook | string (URL) | No | DO v1.6.0 and later. You can optionally specify the URL for a webhook. Once the declaration is finished processing, DO POSTs the response message to the specified endpoint. This feature works both on declarations that require and do not require a reboot to finish processing. | ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| label | string | No | Optional friendly label for this declaration. | ++--------------------+--------------------------------+------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +| + +**Example of the request sent to the webhook** + +.. code-block:: shell + POST / HTTP/1.1 + Content-Type: application/json + + { + "id": "a54b479c-9233-4ac3-b7bd-42f9e6d6e8e7", + "selfLink": "https://localhost/mgmt/shared/declarative-onboarding/task/a54b479c-9233-4ac3-b7bd-42f9e6d6e8e7", + "result": { + "class": "Result", + "code": 200, + "status": "OK", + "message": "success" + }, + "declaration": { + "schemaVersion": "1.0.0", + "class": "Device", + "webhook": "https://example.com/myHook", + "async": false, + "Common": { + "class": "Tenant", + "hostname": "bigip.example.com" + } + } + } + + +| .. _common-class: Common class ```````````` -The next lines of the declaration set the partition (tenant) on the BIG-IP in which all other objects are placed. This **must** be Common. All of the other parameters in Declarative Onboarding are under this Common class. +The next lines of the declaration set the partition (tenant) on the BIG-IP in which all other objects are placed. This **must** be Common. All of the other parameters in BIG-IP Declarative Onboarding are under this Common class. -While not strictly required, you must include Common and the tenant class to set any other parameters in Declarative Onboarding; therefore the required column is set to Yes for the Tenant class. +While not strictly required, you must include Common and the tenant class to set any other parameters in BIG-IP Declarative Onboarding; therefore the required column is set to Yes for the Tenant class. For more information, see |devicecommon| in the Schema Reference. -.. IMPORTANT:: If you set a hostname in the Common class, you cannot use the hostname property in the System class (introduced in DO 1.8.0). We recommend using the :ref:`system-class` for hostname (and have updated this example to move hostname to System). +.. IMPORTANT:: If you set a hostname in the Common class, you cannot use the hostname property in the System class (introduced in BIG-IP DO 1.8.0). We recommend using the :ref:`system-class` for hostname (and have updated this example to move hostname to System). .. NOTE:: For the rest of the classes on this page, the required column in the tables applies only if you are using the class in the heading. None of the classes are required. @@ -119,21 +156,19 @@ For more information, see |devicecommon| in the Schema Reference. \* The required column applies only if you are using this class. +| + .. _system-class: System class ```````````` -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The **autoCheck** property is available in DO 1.13 and later. The **autoPhonehome** property is available in DO v1.10.0 and later. - -The next lines of the declaration set the system-level options. This includes inactivity timeouts for CLI and Console sessions, and the ability to disable the phonehome property (see the table for details) in DO 1.10.0 and later. +The next lines of the declaration set the system-level options. This includes inactivity timeouts for CLI and Console sessions, and the ability to disable the phonehome property (see the table for details) in BIG-IP DO 1.10.0 and later. For more information, see |systemclass| in the Schema Reference. Also see :ref:`The System Class example` for an example declaration. .. IMPORTANT:: If you set a hostname in the Common class, you cannot use the hostname property in the System class. We recommend using the System class for hostname -The name *mySystem* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object however you'd like, but it must have a name. +The name *mySystem* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object anything, but it must have a name. This snippet includes the **autoCheck** property which is not in the full declaration at the top of this page. @@ -172,15 +207,26 @@ This snippet includes the **autoCheck** property which is not in the full declar \* The required column applies only if you are using this class. +| + .. _license-class: License class ````````````` The next lines of the declaration set the licensing options if you are using an F5 Bring Your Own License (BYOL). If your BIG-IP system already has a license (for example, you are using a pay-as-you-go (PAYG) license), you do not need this class. Contact your F5 sales representative if you require a license. -For more information, see |licenseclass| in the Schema Reference. +For more information and a full list of properties, see |licenseclass| in the Schema Reference. + +The name *myLicense* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object anything, but it must have a name. + +BIG-IP Declarative Onboarding 1.24 introduced the optional **chargebackTag** property, the value of which is a text string that can be used as a charge back tag, making it easier to track license costs. +BIG-IP Declarative Onboarding 1.38 introduced the **revokeCurrent** property, which allows you to revoke the current license when relicensing a BIG-IP. + +**New behavior in DO 1.37** +If the BIG-IP has its license revoked outside of DO using `tmsh revoke sys license`, and a declaration is submitted with a license object, the BIG-IP now attempts to license the machine. Previously, if the license on the device had been revoked, the overwrite setting did not re-install the license. + +Note that if the `overwrite` boolean is set to **true**, the BIG-IP will always attempt to license the machine. -The name *myLicense* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object however you'd like, but it must have a name. .. code-block:: javascript @@ -209,9 +255,12 @@ The name *myLicense* we use in this example is arbitrary; it is not used anywher +--------------------+--------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | overwrite | true, **false** | No | Whether or not to overwrite the license if the device is already licensed (not shown in the example) | +--------------------+--------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| chargebackTag | string | No | An optional string that can be used as a charge back tag (not shown in the example) | ++--------------------+--------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ \* The required column applies only if you are using this class. +| .. _dns-class: @@ -219,9 +268,9 @@ DNS class ````````` The next lines of the declaration set the DNS options on the BIG-IP system. For more information, see |dnsclass| in the Schema Reference. -The name *myDNS* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object however you'd like, but it must have a name. +The name *myDNS* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object anything, but it must have a name. -.. IMPORTANT:: If you are configuring DNS in your declaration, Declarative Onboarding disables DHCP for DNS. +.. IMPORTANT:: If you are configuring DNS in your declaration, BIG-IP Declarative Onboarding disables DHCP for DNS. .. code-block:: javascript @@ -255,15 +304,17 @@ The name *myDNS* we use in this example is arbitrary; it is not used anywhere in \* The required column applies only if you are using this class. +| + .. _ntp-class: NTP class ````````` The next lines of the declaration set the NTP (network time protocol) options on the BIG-IP. For more information, see |ntpclass| in the Schema Reference. -The name *myNTP* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object however you'd like, but it must have a name. +The name *myNTP* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object anything, but it must have a name. -.. IMPORTANT:: If you are configuring NTP in your declaration, Declarative Onboarding disables DHCP for NTP. +.. IMPORTANT:: If you are configuring NTP in your declaration, BIG-IP Declarative Onboarding disables DHCP for NTP. For instructions on how to get a current list of timezones on the BIG-IP, see https://support.f5.com/csp/article/K9098. To quickly view a static list that @@ -298,6 +349,7 @@ For instructions on how to get a current list of timezones on the BIG-IP, see ht \* The required column applies only if you are using this class. +| .. _user-class: @@ -305,11 +357,13 @@ User class `````````` The next lines of the declaration create (or modify) the users and their associated roles and access control. For more information, see |userclass| in the Schema Reference. -If you are modifying the root password, you must supply the existing root password (**default** on a new BIG-IP). All other user accounts, including admin, do not have this requirement. As mentioned in the :ref:`prereqs`, if you are using BIG-IP v14.0 or later, the root password may be the same as your admin password you reset before installing Declarative Onboarding. +If you are modifying the root password, you must supply the existing root password (**default** on a new BIG-IP). All other user accounts, including admin, do not have this requirement. As mentioned in the :ref:`prereqs`, if you are using BIG-IP v14.0 or later, the root password may be the same as your admin password you reset before installing BIG-IP Declarative Onboarding. .. IMPORTANT:: The following examples include passwords that may not be valid for BIG-IP v14.0 and later. See |pass| for specific requirements. -Note that the **keys** property is not included in the example at the top of this page, so the line numbers for this section will not line up with that example. +The **keys** property is not included in the example at the top of this page, so the line numbers for this section will not line up with that example. + +.. NOTE:: DO 1.35 introduced the **forceInitialPasswordChange** property for the User class. See the :ref:`User class example` for details. @@ -384,7 +438,7 @@ Note that the **keys** property is not included in the example at the top of thi +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | shell | **tmsh**, bash, none (non-root only) | No | The shell you want the user to be able to use. The default is tmsh. In Declarative Onboarding 1.1.0 and later, you can use **none** when creating non-root users. | +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| keys | array of strings | No | DO 1.5.0+ only: An array of public keys for the user. The authorized_keys file will be overwritten with this value (note default of []). If the user is root, the master key will be preserved. See :ref:`Keys example ` | +| keys | array of strings | No | DO 1.5.0+ only: An array of public keys for the user. The authorized_keys file will be overwritten with this value (note default of []). If the user is root, the primary key will be preserved. See :ref:`Keys example ` | +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -399,9 +453,9 @@ Provision class ``````````````` The next lines of the declaration set the provisioning options on the BIG-IP. For information on the available modules, see |f5|, and for information on provisioning levels, see |prov|. By default, the BIG-IP has the Local Traffic Manager (ltm) provisioned as nominal. For more information, see |provisionclass| in the Schema Reference. -The name *myProvisioning* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object however you'd like, but it must have a name. +The name *myProvisioning* we use in this example is arbitrary; it is not used anywhere in the BIG-IP configuration. You can name this object anything, but it must have a name. -.. NOTE:: Provisioning CGNAT is currently only available in TMOS versions 15.0 and later. |br| Provisioning SSL Orchestrator (SSLO) is available in DO 1.11 and later. +.. NOTE:: Provisioning CGNAT is currently only available in TMOS versions 15.0 and later. |br| Provisioning SSL Orchestrator (SSLO) is available in BIG-IP DO 1.11 and later. @@ -431,14 +485,16 @@ The name *myProvisioning* we use in this example is arbitrary; it is not used an \* The required column applies only if you are using this class. +| + .. _vlan-class: VLAN class `````````` The next lines of the declaration configure VLANs on the BIG-IP system. In this case, the name you give the VLAN class is used for the name of the VLAN on the BIG-IP. For more information, see |vlanclass| in the Schema Reference. -**New in DO 1.7.0 and later** -Declarative Onboarding v1.7.0 and later includes the **cmp-hash** property, which is not included in this example declaration. For information on this property, see the table below the example, and :ref:`CMP Hash example`. +**New in BIG-IP DO 1.7.0 and later** +BIG-IP Declarative Onboarding v1.7.0 and later includes the **cmp-hash** property, which is not included in this example declaration. For information on this property, see the table below the example, and :ref:`CMP Hash example`. @@ -491,12 +547,16 @@ Declarative Onboarding v1.7.0 and later includes the **cmp-hash** property, whic \* The required column applies only if you are using this class. +| + .. _selfip-class: Self IP class ````````````` The next lines of the declaration configure self IP address(es) on the BIG-IP system. In this case, the name you give the Self IP class is used for the name of the Self IP on the BIG-IP. +.. IMPORTANT:: Beginning with DO 1.36.0, the default value for **allowService** on a self IP address changed from **default** to **none**. This change helps DO be more secure and consistent with TMSH. + For more information, see |ntpclass| in the Schema Reference. @@ -506,7 +566,7 @@ For more information, see |ntpclass| in the Schema Reference. "external-self": { "class": "SelfIp", - "address": "1.2.3.4/24", + "address": "192.0.2.4/24", "vlan": "external", "allowService": "none", "trafficGroup": "traffic-group-local-only" @@ -537,6 +597,7 @@ For more information, see |ntpclass| in the Schema Reference. \* The required column applies only if you are using this class. +| .. _route-class: @@ -576,6 +637,8 @@ In this example, we use the name **default**, which sets the default route on th \* The required column applies only if you are using this class. +| + .. _mgmtroute-class: Management Route class @@ -592,8 +655,8 @@ For more information, see |mgmtrouteclass| in the Schema Reference. "managementRoute": { "class": "ManagementRoute", - "gw": "1.2.3.4", - "network": "4.3.2.1", + "gw": "192.0.2.4", + "network": "192.0.2.1", "mtu": 1000, "type": "interface" }, @@ -616,12 +679,13 @@ For more information, see |mgmtrouteclass| in the Schema Reference. \* The required column applies only if you are using this class. +| .. _routedomain-class: Route Domain class `````````````````` -The next lines of the declaration configure route domains on the BIG-IP system. For specific information on Route Domains, see the |rddocs|. For more information on Route Domains in DO, see |routedomainclass| in the Schema Reference. +The next lines of the declaration configure route domains on the BIG-IP system. For specific information on Route Domains, see the |rddocs|. For more information on Route Domains in BIG-IP DO, see |routedomainclass| in the Schema Reference. With Route Domains, the **id** is required, and you use the id as an identifier in other parts of the declaration. You can see a specific example of this in :ref:`Route Domain example`. @@ -684,12 +748,13 @@ With Route Domains, the **id** is required, and you use the id as an identifier \* The required column applies only if you are using this class. +| .. _dbvars-class: .. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - Support for database variables is available in Declarative Onboarding 1.1.0 and later. + Support for database variables is available in BIG-IP Declarative Onboarding 1.1.0 and later. DB Variable class @@ -740,9 +805,6 @@ The next lines of the declaration enable the ability to set arbitrary database v Provisioning Levels - - - .. |f5| raw:: html F5 product modules @@ -821,4 +883,4 @@ The next lines of the declaration enable the ability to set arbitrary database v .. |k15000| raw:: html - K15000 \ No newline at end of file + K15000 diff --git a/docs/conf.py b/docs/conf.py index f9590c31..214788dd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../')) import f5_sphinx_theme - +import re # -- General configuration ------------------------------------------------ @@ -75,7 +75,7 @@ # General information about the project. project = u'F5 Declarative Onboarding' -copyright = u'2020, F5 Networks' +copyright = u'2023, F5 Networks' author = u'F5 Networks' # The version info for the project you're documenting, acts as replacement for @@ -85,7 +85,7 @@ # The short X.Y version. version = u'' # The full version, including alpha/beta/rc tags. -release = u'1.14.0' +release = u'1.37.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -126,7 +126,13 @@ # documentation. # html_theme_options = { - 'next_prev_link': True} + 'next_prev_link': True, + 'version_selector': True} + +html_context = { + 'version_meta_path': '/products/extensions/f5-declarative-onboarding/versions.json', + 'project_safe': re.sub('[^A-Za-z0-9]+', '', project) +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/container-examples.rst b/docs/container-examples.rst deleted file mode 100644 index fe481c03..00000000 --- a/docs/container-examples.rst +++ /dev/null @@ -1,19 +0,0 @@ -. _contexamples: - -Container example declarations ------------------------------- - - -1: Using Declarative Onboarding in a container -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is an example of a declaration for use in a container. It contains the **DO** class, which contains information about the target BIG-IP device. See :doc:`do-container` for information about the container and the DO class. - -The items specific to the DO class are highlighted. - -.. literalinclude:: ../examples/viaASG.json - :language: json - :emphasize-lines: 2-6 - -:ref:`Back to top` - -| \ No newline at end of file diff --git a/docs/declarations/auth.rst b/docs/declarations/auth.rst new file mode 100644 index 00000000..c9bf1946 --- /dev/null +++ b/docs/declarations/auth.rst @@ -0,0 +1,191 @@ +.. _auth-examples: + +Authentication Examples +----------------------- +This section contains example declarations concerning authentication. + +.. _keys: + +Adding public SSH keys to a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we are adding public SSH keys to the root user and a guestUser. This can provide a higher level of security and easier automation. + +**Important notes about using the keys property** + +- Only the root user's primary key (noted by the ``Host Processor Superuser``), in authorized_keys will be preserved. All other keys configured prior to running this declaration, WILL BE DELETED. +- If the **keys** field is left empty it will default to an empty array. This means leaving it empty will clear the authorized_keys file, except for the root's master key. +- For non-root users, the path to the authorized_keys is **/home/{username}/.ssh/authorized_keys**. +- For root, the path is **/root/.ssh/authorized_keys**. +- BIG-IP DO will set the non-root user's .ssh directory permissions to 700, with the authorized_keys permissions set to 600. + +.. literalinclude:: ../../examples/publicKeys.json + :language: json + :emphasize-lines: 13-16, 27-30 + + +:ref:`Back to top` + +| + +.. _authmethods: + +Configuring BIG-IP authentication methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to configure RADIUS, LDAP, and TACACS authentication in a BIG-IP Declarative Onboarding declaration using the **Authentication** class. The authentication class can (but does not have to) contain multiple authentication method subclasses, but only one can be enabled at a time using the **enableSourceType** property (which matches the BIG-IP UI behavior). + +This example declaration contains all three authentication methods with the **enableSourceType** property set to **radius**. It also includes the SSL options for LDAP introduced in BIG-IP DO 1.13. + +For more information on options and BIG-IP DO usage, see |auth| and the subsequent entries in the Schema Reference. + +.. NOTE:: We updated this example for the following: |br| - BIG-IP DO 1.17 includes a CA certificate for LDAP using the new **sslCaCert** property. |br| - BIG-IP DO 1.21 includes the ability to enable or disable LDAP referral chasing using the new **referrals** Boolean (BIG-IP 15.1 and later only). |br| See |authldap| in the Schema Reference for BIG-IP DO information and BIG-IP DO usage. |br| **IMPORTANT**: If you attempt to use the example declaration on a previous version that does not include one of these features, it will fail. You can remove the lines highlighted in yellow for previous versions of BIG-IP DO. + +In the following declaration snippet we show only the classes related to authentication. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. literalinclude:: ../../examples/authMethods.json + :language: json + :emphasize-lines: 46, 56-60 + +:ref:`Back to top` + +| + +.. _remoterole: + +Configuring Remote Roles for authentication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to configure a remote role for authentication using the **RemoteAuthRole** class. See |loref| in the Schema reference for a description of each of the parameters for this class. + +**Important**: The BIG-IP only allows one role per user for each partition/tenant. Because some remote servers allow multiple user roles, the BIG-IP uses the **lineOrder** parameter to choose one of the conflicting roles for the user at login time. In these cases, the system chooses the role with the lowest line-order number. See |lineorder| in the BIG-IP documentation for more information and examples. + +In the following declaration snippet we show only the classes related to remote auth roles. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. literalinclude:: ../../examples/remoteRoles.json + :language: json + +:ref:`Back to top` + +| + +.. _sshex: + +Configuring SSHD settings in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure SSHD (SSH daemon) settings in a BIG-IP Declarative Onboarding declaration. For usage and options, see |sshd| in the Schema Reference. + +In the following declaration, we show only the SSHD class. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +**New in BIG-IP DO 1.15** |br| +BIG-IP Declarative Onboarding v1.15 and later includes the ability to set the source IP addresses that are allowed to log into the system, using the new **allow** property. You can allow all addresses by using the **all** value, or disallow all addresses using the **none** value; otherwise, you can specify an array of IP address as shown in the updated example. + +.. IMPORTANT:: If you attempt to use the following declaration on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **allow** property and IP addresses (the hightlighted lines) + +.. literalinclude:: ../../examples/sshd.json + :language: json + :emphasize-lines: 10-14 + +:ref:`Back to top` + +| + +.. _example18: + +Updating the TLS/SSL Device Certificate in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example declaration shows how you can create/upload a device certificate in a BIG-IP Declarative Onboarding declaration. The BIG-IP system uses the device certificate to authenticate access to the Configuration utility and to accommodate device-to-device communication processes, such as configuration synchronization. + +For more information and how this process works manually, see the KB article |certdoc|. + +A couple of things to note when including certificates and keys in a declaration: + +- BIG-IP BIG-IP DO always writes to **/config/httpd/conf/ssl.crt/server.crt** and **ssl.key/server.key** +- If the device certificate is updated (that is, if the certificate in the declaration does not match the certificate in those directories), BIG-IP DO reboots the BIG-IP device in order to include the updated certificate +- BIG-IP DO makes backups of the certificates and keys in those directories before overwriting the existing certificate and key +- Like other settings in BIG-IP DO, if a subsequent declaration is posted without the certificate, BIG-IP DO will restore the certificate that was there when it first ran. + +See |certclass| in the schema reference for more information and usage. + +.. literalinclude:: ../../examples/deviceCertificate.json + :language: json + +:ref:`Back to top` + +| + +.. _rolevar: + +Using variables in some remote role properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can use variable expressions for some of the properties in the RemoteAuthRole class (see :ref:`remoterole` for the example without variables). This allows you to reference variables that you defined in your AAA system in a BIG-IP Declarative Onboarding declaration. + +There are two important notes for using this feature: + +- When you use variables, they MUST start with **%**. +- You can currently use variables with the **console**, **role**, and **userPartition** properties. + +See |loref| in the schema reference for more information and usage for RemoteAuthRole. + +.. literalinclude:: ../../examples/remoteRoleVariableFields.json + :language: json + +:ref:`Back to top` + +| + +.. _passwordPolicy: + +Configuring a BIG-IP password policy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for the **PasswordPolicy** class is available in BIG-IP DO v1.33 and later. + + +This example shows how you can use the **PasswordPolicy** class introduced in BIG-IP DO 1.33. This class allows you to set a variety of parameters to define a password policy. + +See |pp| in the schema reference for specific details on each of the parameters in the PasswordPolicy class, as well as DO usage. + +.. literalinclude:: ../../examples/passwordPolicy.json + :language: json + +:ref:`Back to top` + + + +.. |certclass| raw:: html + + DeviceCertificate + +.. |certdoc| raw:: html + + Updating a self-signed SSL device certificate on a BIG-IP system + +.. |sshd| raw:: html + + SSHD + +.. |lineorder| raw:: html + + Line Order + +.. |loref| raw:: html + + RemoteAuthRole Class + +.. |auth| raw:: html + + Authentication + +.. |br| raw:: html + +
+ +.. |authldap| raw:: html + + Authentication_ldap + +.. |pp| raw:: html + + PasswordPolicy + + + diff --git a/docs/declarations/basic.rst b/docs/declarations/basic.rst new file mode 100644 index 00000000..d8a6d88b --- /dev/null +++ b/docs/declarations/basic.rst @@ -0,0 +1,72 @@ +.. _basic-examples: + +Basic examples +-------------- +This section contains general BIG-IP Declarative Onboarding example declarations. + + +.. _example1: + +Standalone declaration +^^^^^^^^^^^^^^^^^^^^^^ +The following is an example declaration that onboards a standalone BIG-IP system. See :ref:`Composing a Declaration` for specific details on this example. + +.. literalinclude:: ../../examples/onboard.json + :language: json + + +:ref:`Back to top` + +| + +.. _example2: + +Clustered declaration +^^^^^^^^^^^^^^^^^^^^^ +The following is an example declaration that onboards a clustered BIG-IP system. See :ref:`Clustering` for specific details on this example. + +.. literalinclude:: ../../examples/onboardFailover.json + :language: json + +:ref:`Back to top` + +| + +.. _example3: + +Using JSON Pointers +^^^^^^^^^^^^^^^^^^^ +The following is another example using a declaration for use in a container, but in this case, it also contains a number of examples of using JSON pointers in a declaration. For more information on JSON pointers, see :ref:`JSON Pointers`. + +.. literalinclude:: ../../examples/licenseViaBigIqReachableASG.json + :language: json + + +:ref:`Back to top` + +| + +.. _example4: + +User class +^^^^^^^^^^ +The following is an example of the :ref:`User Class`. The User class creates (or modifies) the users and their associated roles and access control. For more information, see |userclass| in the Schema Reference. + +**New in BIG-IP DO 1.35** |br| +BIG-IP DO introduced the **forceInitialPasswordChange** property for the |userclass|. This property allows you to determine whether a password change is required on the first user login. In previous DO versions, DO followed the BIG-IP default behavior of forcing the password change on first user login. The DO default value for **forceInitialPasswordChange** is **true** meaning DO still enforces the password change. If you do not want to force a password change on first login, set this property to **false**. + +In the following declaration, we show only the User class. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. IMPORTANT:: The following declaration snippet has been updated to include the new **forceInitialPasswordChange** property introduced in BIG-IP DO 1.35. If you attempt to use it on a version prior to 1.35, it will fail. To use the example on a previous version, delete the **forceInitialPasswordChange** property at the bottom (and the comma from the previous line). + +.. literalinclude:: ../../examples/user.json + :language: json + :emphasize-lines: 40, 41 + + + +:ref:`Back to top` + +.. |userclass| raw:: html + + User class \ No newline at end of file diff --git a/docs/declarations/bigiq-examples.rst b/docs/declarations/bigiq-examples.rst new file mode 100644 index 00000000..4c1f00ee --- /dev/null +++ b/docs/declarations/bigiq-examples.rst @@ -0,0 +1,284 @@ +.. _iqexamples: + +BIG-IQ example declarations +--------------------------- + +The following are example declarations for licensing with BIG-IQ. See :ref:`Composing a declaration for licensing BIG-IP with a BIG-IQ` for detailed information about composing declarations with BIG-IQ. + +See the |bigiq| documentation for more detailed information on License pool types. See |compat| for information on BIG-IQ and BIG-IP Declarative Onboarding compatibility + +.. NOTE:: In BIG-IP DO 1.17, we updated the example declarations so the BIG-IP password in the License class matches the one set in the User class, as required by BIG-IP DO. + + +.. _bigiq1: + +Licensing with BIG-IQ: Regkey Pool - Route to BIG-IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following is an example of using a BIG-IQ to license your BIG-IP systems, where the BIG-IQ has an existing route to the BIG-IP. In this example, our existing BIG-IQ license pool is a RegKey pool that contains BIG-IP VE RegKeys. Because the BIG-IP VE is reachable (has a route to the BIG-IQ), we also specify the BIG-IP user name and password. + +.. NOTE:: Currently, to use a RegKey pool the BIG-IP must be reachable from the BIG-IQ. + +The entire *License* class is unique to using BIG-IQ for licensing, so the items specific to RegKey pools are highlighted. + +.. literalinclude:: ../../examples/licenseViaBigIqRegKeyPool.json + :language: json + :emphasize-lines: 15-17 + +:ref:`Back to top` + +| + +.. _bigiq2: + +Licensing with BIG-IQ: Utility Pool - Route to BIG-IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, our BIG-IQ license pool is a utility (subscription) pool. Utility pools contain licenses for BIG-IP services you grant for a specific unit of measure (hourly, daily, monthly, or yearly). + +Utility pools include a additional parameters: **skuKeyword1** and **skuKeyword2**, and **unitOfMeasure** (see :ref:`license-pool` for details). + +We've highlighted the lines that are specific to this utility and Route example (reachable=true). + +**New in BIG-IP DO 1.24** |br| +BIG-IP Declarative Onboarding 1.24 introduced the **chargebackTag** property to the License class. **chargebackTag** is an optional text string which can be used as a charge back tag, making it easier to track license costs. + +.. WARNING:: If you attempt to use this example a BIG-IP Declarative Onboarding version prior to 1.24, it will fail. On previous versions, remove line 22. + +.. literalinclude:: ../../examples/licenseViaBigIqUtilityReachable.json + :language: json + :emphasize-lines: 16-22 + +:ref:`Back to top` + +| + +.. _bigiq3: + +Licensing with BIG-IQ: Utility Pool - No Route to BIG-IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following is another example of using a BIG-IQ to license your BIG-IP systems with a utility pool. However, in this case the BIG-IQ does **not** have an existing route to the BIG-IP. + +For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as BIG-IP Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). + +**New in BIG-IP DO 1.24** |br| +BIG-IP Declarative Onboarding 1.24 introduced the **chargebackTag** property. **chargebackTag** is an optional text string which can be used as a charge back tag, making it easier to track license costs. + +.. WARNING:: If you attempt to use this example a BIG-IP Declarative Onboarding version prior to 1.24, it will fail. On previous versions, remove line 22. + +In this example, we've highlighted the lines that are specific to this utility and No Route example (reachable=false). See :ref:`Composing a declaration for licensing BIG-IP with a BIG-IQ` for specific details on this example. + +.. literalinclude:: ../../examples/licenseViaBigIqUtilityUnreachable.json + :language: json + :emphasize-lines: 16-22 + +:ref:`Back to top` + +| + +.. _bigiq4: + +Licensing with BIG-IQ: Purchased Pool - Route to BIG-IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, our BIG-IQ license pool is a Purchased pool. A Purchased pool is a prepaid pool of a specific number of concurrent license grants for a single BIG-IP service, such as LTM. + +Because the BIG-IP VE is reachable (has a route to the BIG-IQ), we also specify the BIG-IP user name and password. + +.. literalinclude:: ../../examples/licenseViaBigIqPurchasedPoolReachable.json + :language: json + :emphasize-lines: 16-18 + +:ref:`Back to top` + +| + +.. _bigiq5: + +Licensing with BIG-IQ: Purchased Pool - No Route to BIG-IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example also uses a Purchased pool, but without a route to the BIG-IP. + +For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as BIG-IP Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). + +**New in BIG-IP DO 1.15** |br| +BIG-IP DO 1.15 adds the **tenant** property to the License class. This property allows you to specify an optional description for the license. This feature is useful in autoscale solutions managed by a BIG-IQ. The BIG-IP DO tenant property is prepended to the BIG-IQ tenant property. The BIG-IQ tenant property is *management address,hostname* by default, so when using the BIG-IP DO property, it becomes *BIG-IP DO-tenant-property,management-address,hostname*. This feature is only supported when **reachable** is **false**. + +.. IMPORTANT:: The following declaration has been updated to include the new Tenant property introduced in BIG-IP DO 1.15. If you attempt to use it on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **tenant** property at the bottom of the **License** class. + +.. literalinclude:: ../../examples/licenseViaBigIqPurchasedPoolUnreachable.json + :language: json + :emphasize-lines: 16-17 + +:ref:`Back to top` + +| + + + +.. _revoke: + + +Revoking a BIG-IP license from BIG-IQ without relicensing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following is an example of using BIG-IQ to revoke a license from an unreachable BIG-IP VE using **revokeFrom** and specifying the license pool. In this example, we are only revoking the license, and not relicensing the BIG-IP VE. See See :ref:`Revoking a license using BIG-IQ` for specific details on this example. + +.. literalinclude:: ../../examples/revokeViaBigIqUnreachable.json + :language: json + :emphasize-lines: 14 + + +:ref:`Back to top` + +| + +.. _relicense: + + +Revoking and relicensing a BIG-IP (with route) from BIG-IQ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following is an example of using BIG-IQ to revoke a license and then relicense a reachable BIG-IP VE. In this example, we are both revoking the initial license and relicensing the BIG-IP VE from a different license pool on the BIG-IQ. The line with the new licensing pool and the revoke line are highlighted. See See :ref:`Revoking a license using BIG-IQ` for specific details on this example. + +.. literalinclude:: ../../examples/reLicenseViaBigIqReachable.json + :language: json + :emphasize-lines: 14-15 + + +:ref:`Back to top` + +| + +.. _relicense-un: + + +Revoking and relicensing a BIG-IP (no route) from BIG-IQ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following is an example of using BIG-IQ to revoke a license and then relicense an unreachable BIG-IP VE. In this example, we are both revoking the initial license and relicensing the BIG-IP VE from a different license pool on the BIG-IQ. Additionally, because the BIG-IP device does not have a route to the BIG-IQ (unreachable), you must use **overwrite = true** to let the BIG-IP VE know the system is overwriting the license. + +For unreachable devices (with no route to BIG-IP), BIG-IP credentials are not required. Instead, you must explicitly indicate the platform on which the device runs (the **hypervisor** field) as BIG-IP Declarative Onboarding cannot automatically detect the value at this time. This is required for the BIG-IQ license activation API request (see :ref:`license-pool` for hypervisor options). + +**New in BIG-IP DO 1.15** |br| +BIG-IP DO 1.15 adds the **tenant** property to the License class. This property allows you to specify an optional description for the license. This feature is useful in autoscale solutions managed by a BIG-IQ. The BIG-IP DO tenant property is prepended to the BIG-IQ tenant property. The BIG-IQ tenant property is *management address,hostname* by default, so when using the BIG-IP DO property, it becomes *BIG-IP DO-tenant-property,management-address,hostname*. This feature is only supported when **reachable** is **false**. + +.. IMPORTANT:: The following declaration has been updated to include the new Tenant property introduced in BIG-IP DO 1.15. If you attempt to use it on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **tenant** property at the bottom of the **License** class. + +We have highlighted the new licensing pool, the revoke line, the hypervisor, and the overwrite line. See :ref:`Revoking a license using BIG-IQ` for specific details on this example. + +.. literalinclude:: ../../examples/reLicenseViaBigIqUnreachable.json + :language: json + :emphasize-lines: 14-15, 20-21 + +:ref:`Back to top` + +| + +.. _relicense-new: + + +Revoking and relicensing a BIG-IP (no route) from a different BIG-IQ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example is similar to example 9, however in this case, we are using a different BIG-IQ device to revoke and relicense the BIG-IP VE from an unreachable BIG-IP VE. In this case, we specify additional information in the *revokeFrom* property to reference the BIG-IQ that initially licensed the BIG-IP VE. Again, specifying the appropriate hypervisor is required. See :ref:`Revoking a license using BIG-IQ` for specific details on this example. + +**New in BIG-IP DO 1.15** |br| +BIG-IP DO 1.15 adds the **tenant** property to the License class. This property allows you to specify an optional description for the license. This feature is useful in autoscale solutions managed by a BIG-IQ. The BIG-IP DO tenant property is prepended to the BIG-IQ tenant property. The BIG-IQ tenant property is *management address,hostname* by default, so when using the BIG-IP DO property, it becomes *BIG-IP DO-tenant-property,management-address,hostname*. This feature is only supported when **reachable** is **false**. + +.. IMPORTANT:: The following declaration has been updated to include the new Tenant property introduced in BIG-IP DO 1.15. If you attempt to use it on a version prior to 1.15, it will fail. To use the example on a previous version, delete the **tenant** property at the bottom of the **License** class. + +.. literalinclude:: ../../examples/reLicenseViaNewBigIqUnreachable.json + :language: json + :emphasize-lines: 15-21, 26-27 + + +:ref:`Back to top` + +| + +.. _bigiqdo1: + +Onboarding a BIG-IP in AWS via BIG-IQ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this example, we onboard a BIG-IP VE in AWS using the BIG-IP DO endpoint on the BIG-IQ device. This example uses both targetHost to specify the BIG-IP information, and bigIqSettings. + +See :ref:`do-bigiq-table` for information on the bigIqSettings parameters. These parameters are highlighted in the following declaration. + +See the BIG-IQ API documentation for similar examples for |bigiqazure| and |bigiqvmware|. + +.. literalinclude:: ../../examples/onboardViaBigIqAws.json + :language: json + :emphasize-lines: 49-59 + + +:ref:`Back to top` + +| + +.. _bigiqauth: + +Using an external authentication provider for BIG-IQ licensing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for the **bigiqAuthProvider** property is available in BIG-IP DO v1.18 and later. You must have the authentication provider defined on the BIG-IQ before submitting the declaration. + +In this example, we show how you can reference an external auth provider for BIG-IQ license calls using the **bigiqAuthProvider** property introduced in BIG-IP DO 1.18. The default is to use TMOS as the authentication provider. For more information on BIG-IQ authentication tokens, see |tokendoc| in the BIG-IQ API reference. + +To use this property in your declaration, you must have an existing authentication provider defined on your BIG-IQ. For information on configuring authentication providers, see the BIG-IQ documentation (for example, the |authdoc| chapter gives information on configuring an LDAP authentication provider in BIG-IQ 7.0). + + +.. literalinclude:: ../../examples/licenseViaBigIqPoolAuthProvider.json + :language: json + :emphasize-lines: 15 + + +:ref:`Back to top` + +| + +.. _bigiqhex: + +Onboarding a BIG-IP in Alibaba via BIG-IQ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to specify the Alibaba hypervisor in a BIG-IP Declarative Onboarding declaration via BIG-IQ (no route). BIG-IQ itself uses the hex value **0x01000013** for Alibaba to work around a known issue. BIG-IP DO v1.21 adds the ability to specify this hex value in the **hypervisor** property when licensing using a BIG-IQ pool. + + +.. literalinclude:: ../../examples/licenseViaBigIqPoolUnreachableHEXHypervisor.json + :language: json + :emphasize-lines: 18 + + +:ref:`Back to top` + + + + + +.. |br| raw:: html + +
+ +.. |bigiq| raw:: html + + BIG-IQ + +.. |compat| raw:: html + + K54909607 + + +.. |bigiqazure| raw:: html + + Microsoft Azure + +.. |bigiqvmware| raw:: html + + VMware Cloud + +.. |tokendoc| raw:: html + + Auth Token by Login + +.. |authdoc| raw:: html + + LDAP User Authentication + + diff --git a/docs/declarations/clustering.rst b/docs/declarations/clustering.rst new file mode 100644 index 00000000..5fd13578 --- /dev/null +++ b/docs/declarations/clustering.rst @@ -0,0 +1,117 @@ +.. _cluster-examples: + +Clustering Examples +------------------- +This section contains examples for clustering BIG-IP devices. + + +Clustered declaration +^^^^^^^^^^^^^^^^^^^^^ +The following is an example declaration that onboards a clustered BIG-IP system. See :ref:`Clustering` for specific details on this example. + +.. literalinclude:: ../../examples/onboardFailover.json + :language: json + +:ref:`Back to top` + +| + +.. _example17: + +Clustered declaration with IP addresses for Device Group owner and members +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following is an example declaration that onboards a clustered BIG-IP system, but shows how you can use an IP address for the Device Group members and owner. + +See :ref:`devicegroup` for more information. + +.. literalinclude:: ../../examples/clusterWithIpAddresses.json + :language: json + +:ref:`Back to top` + +| + +.. _founi: + +Configuring multiple failover unicast addresses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how to specify multiple failover unicast addresses using BIG-IP Declarative Onboarding 1.15 and later. The unicast addresses you specify are the main address that other devices in the device group use to communicate continually with the local device to assess the health of that device. For more information on failover on the BIG-IP, see |failover|. + +For additional information, see :ref:`failover-uni-class` on the Clustering page. See |unicast| in the Schema Reference for BIG-IP DO usage and options. + +To use this feature: + +- The failover unicast addresses must be pointing at IP addresses on the BIG-IP system (Self IP addresses) +- Self IPs require a VLAN. Some systems, such as 1 NIC BIG-IP systems, are not able to have multiple VLANs. Check the device on which you are deploying a declaration using this feature. + +In the following example, the declaration creates a VLAN, that is then used by 2 external Self IP addresses, and then updates the device with two Failover Unicast addresses. + +.. literalinclude:: ../../examples/multipleFailoverUnicasts.json + :language: json + +:ref:`Back to top` + +| + +.. _example29: + +Configuring connection and persistence mirroring +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can include connection and persistence mirroring information in a BIG-IP Declarative Onboarding declaration. + +The connection and persistence mirroring feature allows you to configure BIG-IP systems in a high availability (HA) configuration to duplicate connection and persistence information to peer members of the BIG-IP device group. This feature provides higher reliability but may affect system performance. For more information, see the |mirrorkb| article on AskF5. + +See |mirrorref| in the Schema Reference for BIG-IP DO usage and options. Also see :ref:`mirrorip` on the Clustering page. + +.. literalinclude:: ../../examples/mirrorIp.json + :language: json + +:ref:`Back to top` + +| + +.. _multicast: + +Configuring Failover Multicast settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can configure Failover Multicast settings in a BIG-IP Declarative Onboarding declaration using the **FailoverMulticast** class introduced in BIG-IP DO 1.17. When you use this class, the system sends multicast messages associated with failover on the interface, address, and port you specify. For more information on Failover options on the BIG-IP, see |multicastdoc| in the product documentation. + +When configuring Failover Multicast, all three fields (**interface**, **address**, and **port**) are required. The address cannot have a CIDR. + +If you do not specify an available interface name, the system will show an error which includes a list of available interfaces. If you specify a value **none** for the interface, BIG-IP DO disables Failover Multicast on the BIG-IP. + +See |multi| in the Schema Reference for BIG-IP DO usage and options. + +.. NOTE:: The following example only includes the FailoverMulticast class, which can be used as a part of a larger declaration. + +.. literalinclude:: ../../examples/failoverMulticast.json + :language: json + +:ref:`Back to top` + + +.. |mirrorkb| raw:: html + + Overview of connection and persistence mirroring + +.. |mirrorref| raw:: html + + MirrorIp + +.. |failover| raw:: html + + Failover documentation + +.. |unicast| raw:: html + + FailoverUnicast + +.. |multicastdoc| raw:: html + + Managing Failover + + +.. |multi| raw:: html + + FailoverMulticast + diff --git a/docs/declarations/gslb.rst b/docs/declarations/gslb.rst new file mode 100644 index 00000000..7eb06368 --- /dev/null +++ b/docs/declarations/gslb.rst @@ -0,0 +1,143 @@ +.. _gslb-examples: + +GSLB Examples +------------- +This section contains examples for GSLB (Global Server Load Balancing), which requires the BIG-IP DNS (formerly GTM) module to be licensed and provisioned. + + +.. _globalgslb: + +Configuring global GSLB settings in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure global GSLB settings in BIG-IP DO 1.17 and later using the **GSLBGlobals** class. This class uses the **GSLBGlobals_general** properties (synchronizationEnabled synchronizationGroupName, synchronizationTimeout, and synchronizationTimeTolerance) to configure GSLB global settings on the BIG-IP. + +For more details on the properties and BIG-IP DO usage, see |gslbglobal| and |gslbgen| in the Schema Reference. + +For information on BIG-IP DNS, see the |dns| for your BIG-IP version. + +This example only includes the GSLBGlobals class, which can be used as a part of a larger BIG-IP DO declaration. + +.. literalinclude:: ../../examples/gslbGlobals.json + :language: json + +| + +.. _gslbdc: + +Configuring a GSLB Data Center +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure a GSLB Data Center in BIG-IP DO 1.18 and later using the **GSLBDataCenter** class. This allows you to configure GSLB Data Center properties in a BIG-IP Declarative Onboarding declaration. + +All of the resources on your network are associated with a data center. BIG-IP DNS consolidates the paths and metrics data collected from the servers, virtual servers, and links in the data center. BIG-IP DNS uses that data to conduct load balancing and route client requests to the best-performing resource based on different factors. For information on BIG-IP DNS, including GSLB Data Centers, see the |dns| for your BIG-IP version. + +For details on the available properties and BIG-IP DO usage, see |gslbdata| in the Schema Reference. + + + +This example only includes the GSLBDataCenter class, which can be used as a part of a larger BIG-IP DO declaration. + +.. literalinclude:: ../../examples/gslbDataCenter.json + :language: json + +| + +.. _gslbserver: + +Configuring a GSLB Server +^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure a GSLB Server in BIG-IP DO 1.18 and later using the **GSLBServer** class. This allows you to configure GSLB Server properties in a BIG-IP Declarative Onboarding declaration. + +A GSLB Server defines a physical system on the network. Servers contain the virtual servers that are the ultimate destinations of DNS name resolution requests. For information on BIG-IP DNS, including GSLB Servers, see the |dns| for your BIG-IP version. + +BIG-IP DO 1.19 added support for Prober pools and GSLB virtual servers to GSLB Servers. For information on Prober pools, see :ref:`prober`. |br| For information on GSLB virtual servers, see the |gslbvipdoc| chapter of the documentation. For BIG-IP DO options and usage, see |gslbvip|. + +For details on the available properties and BIG-IP DO usage, see |gslbserver| in the Schema Reference. + +.. IMPORTANT:: Because this example was updated to include a Prober pool and GSLB virtual servers, if you attempt to use the following declaration on a previous version of BIG-IP DO, it will fail. If you are using a version prior to 1.19, you can remove the Prober pool and virtual server lines (in yellow). + +.. literalinclude:: ../../examples/gslbServer.json + :language: json + :emphasize-lines: 9-11, 28, 44-62 + +| + +.. _gslbmonitors: + +Configuring GSLB health monitors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure a GSLB health monitors in a BIG-IP Declarative Onboarding declaration. Health monitors verify the availability and/or performance status of a particular protocol, service, or application. You can configure HTTP, HTTPS, Gateway-ICMP, TCP, or UDP GSLB health monitors in a declaration. + +For information on BIG-IP DNS, including GSLB monitors, see the |dns| for your BIG-IP version. + +For details on the available properties and BIG-IP DO usage, see |gslbmon| in the Schema Reference. + +.. NOTE:: GSLB Monitor has a number of built-in monitors, such as **http** and **http_head_f5**. You cannot use these names in a declaration or it will fail. These default monitors cannot be deleted. + +This example includes each of the available GSLB monitors which you can use as part of a larger BIG-IP Declarative Onboarding declaration. In this declaration, the monitors are all used in the GSLB Server (see :ref:`the GSLB Server example`). + +.. literalinclude:: ../../examples/gslbMonitor.json + :language: json + +| + + +.. _prober: + +Configuring a GSLB prober pool +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure a GSLB prober pool in a BIG-IP Declarative Onboarding declaration. Prober pools contain specific BIG-IP devices that probe data centers and servers. + +For more information on Prober pools, including manual configuration, see |proberkb|. + +For details on the available properties and BIG-IP DO usage, see |gslbpp| in the Schema Reference. + +.. literalinclude:: ../../examples/gslbProberPool.json + :language: json + +| + + + +.. |dns| raw:: html + + DNS/GTM knowledge center + +.. |gslbglobal| raw:: html + + GSLBGlobals + +.. |gslbgen| raw:: html + + GSLBGlobals_general + +.. |gslbdata| raw:: html + + GSLBDataCenter + +.. |gslbserver| raw:: html + + GSLBServer + +.. |gslbmon| raw:: html + + GSLBMonitor + +.. |proberkb| raw:: html + + K08433560: Configuring prober pools + +.. |gslbpp| raw:: html + + GSLBProberPool + +.. |br| raw:: html + +
+ +.. |gslbvip| raw:: html + + GSLBServer-virtualServers + +.. |gslbvipdoc| raw:: html + + Global Server Load Balancing \ No newline at end of file diff --git a/docs/declarations/miscellaneous.rst b/docs/declarations/miscellaneous.rst new file mode 100644 index 00000000..46206f09 --- /dev/null +++ b/docs/declarations/miscellaneous.rst @@ -0,0 +1,364 @@ +.. _misc-examples: + +Miscellaneous Examples +---------------------- +The following are miscellaneous example declarations for BIG-IP. + + + +.. _httpdex: + +Configuring HTTPD settings in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure HTTPD (HTTP daemon) settings in a BIG-IP Declarative Onboarding declaration. For usage and options, see |httpd| in the Schema Reference. + +.. NOTE:: If you use the BIG-IP Configuration utility, we recommend you exit the utility before changes are made to the system using the HTTPD component. Making changes to the system using this component causes a restart of the httpd daemon, and restarting the httpd daemon requires a restart of the Configuration utility. + +In the following declaration, we show only the HTTPD class. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + + +.. literalinclude:: ../../examples/httpd.json + :language: json + +:ref:`Back to top` + +| + +.. _systemex: + +Configuring System settings in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure some System settings in a BIG-IP Declarative Onboarding declaration. This enables you to set auto-timeout values for serial console (CLI) and TMSH interactive mode sessions, as well as set a hostname, if you have not set one in the Common class. + +.. IMPORTANT:: If you set a hostname in the Common class, you cannot use the hostname property in the System class; they are mutually exclusive. + +For usage and options, see |sysclass| in the Schema Reference. + +BIG-IP DO 1.13 introduced the ability to disable the automatic update check feature. The autoCheck property controls whether the BIG-IP checks for and recommends software updates. See |k15000| for more information. + +BIG-IP DO 1.32 introduced the ability to modify the default security banner on the logon screen of the user interface using the **guiSecurityBanner** and **guiSecurityBannerText** properties. When **guiSecurityBanner** is set to **true**, you specify the text you want to display in the **guiSecurityBannerText** property. If you set **guiSecurityBanner** to **false**, the system presents an empty frame in the right portion of the login screen. + +In the following declaration, we show only the System class (including autoCheck introduced in 1.13, and the GUI security banner options in 1.32). You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +**Important**: If you try to use this declaration with a BIG-IP DO version prior to 1.32, it will fail. Either upgrade BIG-IP DO to 1.32, or remove the guiSecurityBanner lines (highlighted in yellow). + + +.. literalinclude:: ../../examples/system.json + :language: json + :emphasize-lines: 15, 16 + +:ref:`Back to top` + +| + +.. _example19: + +Using the userAgent Controls property +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can use the **userAgent** property in the new **Controls** class. The userAgent property allows you to set a unique identifier in usage data. + +This declaration includes the Controls class with userAgent set to **BIG-IQ/7.1 Configured by API**. + +See |controls| in the Schema Reference for more information. + + +.. literalinclude:: ../../examples/userAgent.json + :language: json + +:ref:`Back to top` + +| + +.. _example27: + +Enabling traces in BIG-IP DO responses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can use the **trace** and **traceResponse** properties to enable more visibility into what BIG-IP DO is configuring. These properties are included in the |controls| class. + +.. WARNING:: Trace files may contain sensitive configuration data. + +When **trace** is set to **true** (the default is false), BIG-IP DO creates a detailed trace of the configuration process for subsequent analysis. This information is written to files in the **/tmp** directory where BIG-IP DO is running. |br| +The files are: + +- /tmp/DO_current.json +- /tmp/DO_desired.json +- /tmp/DO_diff.json + + +When **traceResponse** is set to **true** (the default is false), the response (or response to a subsequent GET request in the case of asynchronous requests) contains the same information that would be found in the trace files. + +This example shows both the declaration and the response from BIG-IP DO. + +.. literalinclude:: ../../examples/debugTrace.json + :language: json + +| + +**Example Response** |br| +Here is the response returned by BIG-IP DO from the declaration, showing the trace for the tenant (your output will vary based on the configuration of your device). + + +.. literalinclude:: trace-response.json + :language: json + + +| + +.. _example28: + +Creating Routes in the LOCAL_ONLY partition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how to create a route in a special LOCAL_ONLY partition/tenant using the new **localOnly** property in the Route class. When using this feature, if this partition doesn't exist, BIG-IP Declarative Onboarding creates it. + +This partition is required to configure an Amazon Web Services (AWS) *Across Network* cluster. + +See |route| in the Schema Reference for BIG-IP DO usage and options. + +**Important notes:** + - While BIG-IP DO can create the LOCAL_ONLY partition if it does not exist, it cannot currently delete it, and the partition will remain even if you delete the BIG-IP DO configuration. + - A Route cannot be directly swapped from one partition to another. If you attempt to swap value of **localOnly**, the declaration will fail. As a workaround, change the network of the Route to another IP and set localOnly to what you want it to be. Submit that using BIG-IP DO. Once that is complete, you can change the network to the desired value. + +.. literalinclude:: ../../examples/localOnlyRoutes.json + :language: json + +:ref:`Back to top` + +| + +.. _example30: + +Warning users the BIG-IP is under AS3 automation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can use BIG-IP Declarative Onboarding to discourage unintended configuration changes to a device that is managed by AS3. This example configures an advisory banner using the **DbVariables** class. + +.. literalinclude:: ../../examples/banner.json + :language: json + +:ref:`Back to top` + +| + +.. _example31: + +Increasing the memory allocated to the restjavad daemon +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can use BIG-IP Declarative Onboarding to increase the amount of memory allocated to restjavad, using the **DbVariables** class. + +See (see :ref:`restjavad`) for reasons you may want to increase this memory allocation. + +.. literalinclude:: ../../examples/restjavad.json + :language: json + +:ref:`Back to top` + + +| + +.. _example32: + +Using the dryRun Controls property to test the declaration without deploying it +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can use the **dryRun** property in the |controls| class. + +When **dryRun** is set to **true** (the default is **false**) BIG-IP Declarative Onboarding sends the declaration through all validation checks but does not attempt to deploy the configuration on the target device. The response contains information on what would have been deployed (a diff between the existing configuration and what the declaration would deploy). This can be useful for testing and debugging declarations. + +.. NOTE:: BIG-IP Declarative Onboarding does not report information (diffs) on items such as licensing, users, or device trust. + + +See |controls| in the Schema Reference for more information. + + +.. literalinclude:: ../../examples/dryRun.json + :language: json + +:ref:`Back to top` + + +| + +.. _relic: + +Relicense a BIG-IP while revoking the current license +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for the revoking and relicensing in a declaration is available in BIG-IP DO v1.38 and later. + +In this example, we show how you can use DO to relicense a BIG-IP while at the same time revoke the existing license. + +This declaration uses the **revokeCurrent** property in the |license| introduced in DO 1.38. This property determines whether or not to revoke the current license if the device is already licensed. + +.. NOTE:: Revoking the existing license is skipped if you are relicensing with the same registration key, no matter what value is used in the **revokeCurrent** property. + + +See |license| in the Schema Reference and the :ref:`Composing a Declaration ` page for more information. + + +.. literalinclude:: ../../examples/reLicenseBigIp.json + :language: json + +:ref:`Back to top` + + +| + +.. |br| raw:: html + +
+ +.. |rddoc| raw:: html + + Route Domain documentation + +.. |dagdoc| raw:: html + + Disaggregation DAG modes + +.. |snmpdoc| raw:: html + + Monitoring BIG-IP System Traffic with SNMP + +.. |license| raw:: html + + License Class + +.. |tcref| raw:: html + + TrafficControl Class + +.. |loref| raw:: html + + RemoteAuthRole Class + + +.. |rolesdoc| raw:: html + + Remote User Account Management + +.. |lineorder| raw:: html + + Line Order + +.. |sldocs| raw:: html + + External Monitoring + +.. |slkb| raw:: html + + Configuring remote logging + +.. |slref| raw:: html + + SyslogRemoteServer Class + +.. |cmpdocs| raw:: html + + Additional VLAN Configuration Options + +.. |cmpref| raw:: html + + VLAN Class + +.. |trunkdoc| raw:: html + + Trunk documentation + +.. |trunkref| raw:: html + + Trunk class + +.. |sshd| raw:: html + + SSHD + +.. |httpd| raw:: html + + HTTPD + +.. |sysclass| raw:: html + + System + +.. |certclass| raw:: html + + DeviceCertificate + +.. |certdoc| raw:: html + + Updating a self-signed SSL device certificate on a BIG-IP system + +.. |controls| raw:: html + + Device_Controls + +.. |auth| raw:: html + + Authentication + +.. |k15000| raw:: html + + K15000 + +.. |auditlog| raw:: html + + Audit Logging documentation + +.. |macm| raw:: html + + Mac_Masquerade + +.. |mmkb| raw:: html + + K13502: Configuring MAC masquerade + +.. |vlanfs| raw:: html + + K13297: Overview of VLAN failsafe + +.. |dnsresolver| raw:: html + + DNS_Resolver + + +.. |dnsdoc| raw:: html + + BIG-IP DNS documentation + +.. |tunnel| raw:: html + + Tunnel + +.. |tg| raw:: html + + TrafficGroup + +.. |tgdoc| raw:: html + + BIG-IP Device Service Clustering: Administration + +.. |hagroup| raw:: html + + BIG-IP documentation + +.. |failover| raw:: html + + Failover documentation + +.. |unicast| raw:: html + + FailoverUnicast + +.. |route| raw:: html + + Route + +.. |mirrorkb| raw:: html + + Overview of connection and persistence mirroring + +.. |mirrorref| raw:: html + + MirrorIp + + + diff --git a/docs/declarations/network-objects.rst b/docs/declarations/network-objects.rst new file mode 100644 index 00000000..fe520fad --- /dev/null +++ b/docs/declarations/network-objects.rst @@ -0,0 +1,667 @@ +.. _networkexamples: + +Network Objects +--------------- +The following are example declarations that contain networking objects. + + +.. _rdomain: + +Adding Route Domains to a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to use a Route Domain in a declaration. A route domain is a configuration object that isolates network traffic for a particular application on the network. For more information on Route Domains, see |rddoc|. + +In the following declaration, we include a VLAN to show how to reference a VLAN that is being created. The SelfIp and the Route both show using the RouteDomain with **%100**, which is the **id** of the RouteDomain. + +**New in BIG-IP DO 1.17** |br| +BIG-IP Declarative Onboarding 1.17 added support for specifying a parent route domain. This is the route domain the system searches when it cannot find a route in the configured domain. + +.. IMPORTANT:: The following declaration has been updated to include the **parent** property introduced in BIG-IP DO 1.17. If you attempt to use this declaration on a prior version, it will fail unless you remove the **parent** property. + + +.. literalinclude:: ../../examples/routeDomains.json + :language: json + :emphasize-lines: 21, 25, 28-46, 50 + + +:ref:`Back to top` + +| + +.. _dag: + +Setting the DAG IPv6 prefix length +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to use the DagGlobals class to set or modify the DAG global IPv6 prefix length. DAG Globals contain the global disaggregation settings; see the |dagdoc| documentation for more information. + +In the following declaration snippet, we show only the DagGlobals class. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + + + +.. literalinclude:: ../../examples/dagGlobals.json + :language: json + + +:ref:`Back to top` + +.. _trafcontrol: + +Configuring Traffic Control properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure BIG-IP LTM global traffic control settings (ltm global-settings traffic-control) using a BIG-IP Declarative Onboarding declaration. For descriptions and usage details on these properties, see |tcref| in the Schema Reference. + +In the following declaration snippet we show only the classes related to Traffic Control. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. literalinclude:: ../../examples/trafficControl.json + :language: json + +:ref:`Back to top` + +| + +.. _cmphash: + +Using the CMP Hash property in a VLAN +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Starting in 1.7.0, you have the option of using the **cmp-hash** property on a VLAN. The CMP Hash setting allows all connections from a client system to use the same set of TMMs, improving system performance. For more information, see |cmpdocs| in the BIG-IP documentation. You can also see |cmpref| in the Schema Reference for usage options. + +In the following declaration snippet we show only the VLAN class with cmp-hash using Source Address as the traffic disaggregation method. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. literalinclude:: ../../examples/vlanCmpHash.json + :language: json + +:ref:`Back to top` + +| + +.. _example21: + +Configuring MAC Masquerading on Traffic Groups +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure MAC Masquerading on Traffic Groups. This is a part of the new **MAC_Masquerade** class. + +For detailed information about Mac Masquerade on the BIG-IP, see |mmkb|. + +See |macm| in the Schema Reference for BIG-IP DO usage and options. + + +.. literalinclude:: ../../examples/macMasquerade.json + :language: json + +:ref:`Back to top` + +| + +.. _example22: + +Configuring VLAN Failsafe +^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure VLAN Failsafe settings in a BIG-IP Declarative Onboarding declaration. This is a part of the |cmpref|, and includes the new properties **failsafeEnabled**, **failsafeAction**, and **failsafeTimeout**. + +For detailed information about VLAN Failsafe on the BIG-IP, see |vlanfs|. + +See |cmpref| in the Schema Reference for BIG-IP DO usage and options. + + +.. literalinclude:: ../../examples/vlanFailsafe.json + :language: json + + +:ref:`Back to top` + +| + +.. _example23: + +Configuring a DNS Resolver +^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you create a DNS Resolver in a BIG-IP Declarative Onboarding declaration using the |dnsresolver| class introduced in BIG-IP DO 1.14. The DNS Resolver is the internal DNS resolver the BIG-IP system uses to fetch the internal proxy response. + +See |dnsresolver| in the Schema Reference for BIG-IP DO usage and options. + +For detailed information about the DNS Resolver, see |dnsdoc| on AskF5. + + +.. literalinclude:: ../../examples/dnsResolver.json + :language: json + +| + +.. _example24: + +Configuring a TCP Forward Tunnel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for tunnel types **gre** and **geneve** is available in BIG-IP DO v1.24 and later + +In this example, we show how you create a TCP Forward Network Tunnel in a BIG-IP Declarative Onboarding declaration using the |tunnel| class. + +BIG-IP Declarative Onboarding 1.24 adds two tunnel types: **gre** and **geneve**. In previous versions, **tcp_forward**, for forward proxy connections, was the only supported type of tunnel. + +See |tunnel| in the Schema Reference for BIG-IP DO usage and options. The following example only shows the **tcp_forward** tunnel type. + +.. literalinclude:: ../../examples/tcpForwardTunnel.json + :language: json + +:ref:`Back to top` + +| + +.. _example25: + +Configuring Traffic Groups +^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how to create Traffic Groups using BIG-IP Declarative Onboarding 1.14 and later. A traffic group is a group of configuration objects on a BIG-IP which is able to float to another device in a device group in case of failure. For more information, see :ref:`trafficgroup` on the Clustering page, and |tgdoc|. + +See |tg| in the Schema Reference for BIG-IP DO usage and options. + +.. IMPORTANT:: The HA Score failover method is not currently supported. BIG-IP DO uses the HA Order failover method. |br| |br| Because BIG-IP DO uses HA Order for failover, the declaration must include a hostname, located inside of a deviceGroup. In the following example, the declaration defines a Device Group with a host name. See :ref:`devicegroup` for information on Device Groups. + + +.. literalinclude:: ../../examples/trafficGroups.json + :language: json + +:ref:`Back to top` + +| + +.. _example26: + +Configuring routing prefix lists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can create network routing prefix lists using BIG-IP Declarative Onboarding 1.18 and later. These prefix lists are a part of a larger BGP configuration, and enable you to specify allow and deny actions for each prefix address. + +See |prefix| and |prefixentry| in the Schema Reference for BIG-IP DO usage and options. + +**New in BIG-IP DO 1.23** |br| +BIG-IP DO 1.23 introduced the ability to use strings for the **prefixLengthRange** range property. Previous versions would only accept integers. |br| +**Important** If you try to use the following example on versions prior to 1.23, it will fail. If using a previous version, replace the values in the highlighted lines with integers. + + +The following example contains multiple prefix lists, but no other BIG-IP DO configuration. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + + +.. literalinclude:: ../../examples/routingPrefixList.json + :language: json + :emphasize-lines: 15, 21, 32, 38 + +:ref:`Back to top` + + +| + +.. _bgprouting: + +Configuring BGP Routing in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for BGP routing is available in BIG-IP DO v1.20 and later. BGP Routing is an experimental (Early Access) feature on the BIG-IP. |br| Support for the **ebgpMultihop** property is available in BIG-IP DO 1.24 and later. + +This example shows how you can configure Border Gateway Protocol (BGP) routing in a BIG-IP Declarative Onboarding declaration. + +For an excellent overview of BGP, see the F5 Lightboard lesson |bgpvid|. + +.. IMPORTANT:: BGP Routing is an experimental (Early Access) feature on the BIG-IP system. + +The BGP routing configuration uses the following BIG-IP Declarative Onboarding classes (some of the classes were introduced in previous versions of BIG-IP Declarative Onboarding, but the main **RoutingBGP** class, which is required to use BGP routing, was introduced in BIG-IP DO 1.20). The links go to the Schema Reference for descriptions and BIG-IP DO usage. + +- |routingbgp| +- |routingaspath| +- |prefix| +- |routemap| +- |accesslist| (added in BIG-IP DO 1.24, not included in this example) + +The **RoutingBGP** class contains a number of properties used in the following example, so be sure to see |routingbgp| for descriptions and options. + +**New in BIG-IP DO 1.24** |br| +BIG-IP Declarative Onboarding 1.24 introduced the **ebgpMultihop** property for BGP neighbors. This property allows you to specify between 1 and 255 external BGP members that are not on directly connected networks (the default is **1**). See |ebgp| in the Schema Reference for more information. + +**New in BIG-IP DO 1.28** |br| +BIG-IP Declarative Onboarding 1.28 adds support for specifying route domains in |routingbgp| and |routemap|. + +.. IMPORTANT:: If you try to use the following example with a version prior to 1.28, it will fail. For previous versions, remove the lines in yellow. You can leave the **ebgpMultihop** lines if using a BIG-IP DO version between 1.24 and 1.27. + + +.. literalinclude:: ../../examples/bgp.json + :language: json + :emphasize-lines: 85, 103, 133, 138, 158 + +| + +.. _firewallpolicy: + +Configuring a Firewall policy in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for Firewall policies is available in BIG-IP DO v1.20 and later. You must have BIG-IP AFM licensed. + +This example shows how you can configure a firewall policy in a declaration. BIG-IP Network Firewall policies combine one or more rules and apply them as a combined policy to one context, such as a self IP as shown. + +The AFM features we use in this declaration are well-documented in the |afmdocs|. + +You must have BIG-IP AFM provisioned as shown in the example. + +See |fwp|, |fwal|, |fwpl|, and associated classes in the Schema Reference for descriptions and BIG-IP DO usage. + +.. NOTE:: The **firewallAddressList** class supports using FQDNs, however, FQDNs require a DNS Resolver on the BIG-IP which is not yet configurable using BIG-IP DO. If you want to use FQDNs, you must manually configure a DNS Resolver before submitting the declaration. See |dnsresolverdocs| for manual configuration information. + +.. literalinclude:: ../../examples/firewallPolicy.json + :language: json + +| + +.. _alhvlan: + +Configuring Auto Last Hop on VLANs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can configure Auto Last Hop on VLANs in a BIG-IP Declarative Onboarding declaration. Auto Last Hop allows the system to send return traffic to the MAC address that transmitted the request, even if the routing table points to a different network or interface. As a result, the system can send return traffic to clients even when there is no matching route. + +There are three possible values for the **autoLastHop** property: **enabled**, **disabled**, and **default**, which inherits the value from the global settings. + +For detailed information on Auto Last Hop, see |alh| on AskF5. + +See |cmpref| for description and BIG-IP DO usage. + + +.. literalinclude:: ../../examples/vlanAutoLastHop.json + :language: json + + +| + +.. _manip: + +Specifying a static management IP address in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can specify a management IP address in a BIG-IP Declarative Onboarding declaration using the **ManagementIp** class introduced in BIG-IP DO 1.23. The ability to set a static management IP address is useful in scenarios such as updating the BIG-IP after a NIC swap in the Google Cloud Platform. + +When using **ManagementIp**, you must keep in mind the following: + +- You must also update the ManagementRoute for the new management IP. See |mr|. +- If running remotely (on BIG-IQ), the remote device must be able to route to the new management IP. +- When polling for BIG-IP DO status, use the new management IP. +- If you are *only* changing the mask, BIG-IP DO must delete the existing management IP address. This means it will only work when BIG-IP DO is running on the device being configured (not from BIG-IQ). This is a system limitation not a BIG-IP DO limitation. +- No response is returned if running in synchronous mode. Always use asynchronous mode when changing the management IP address (see |bc|). +- To handle rollback to a dynamically configured IP, do not set the remark for the ManagementIp to 'configured-by-dhcp'. The default value is fine. + +See |mip| for BIG-IP DO usage. + + +.. literalinclude:: ../../examples/managementIp.json + :language: json + +| + +.. _dhcpresv: + +Preserving DHCP routes when adding new management routes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how BIG-IP DO can preserve DHCP Management routes when you are adding new management routes in a BIG-IP DO declaration using 1.23 or later. By default, management routes are assigned by DHCP. In previous versions of BIG-IP DO, when you specified a new management route, BIG-IP DO would remove the route assigned by DHCP. + +This feature provides the ability to preserve those DHCP routes using the new **preserveOrigDhcpRoutes** property set to **true** in the |sysclass| class. + +.. IMPORTANT:: If you do not configure BIG-IP DO to preserve management routes (the default) but specify management routes in the declaration, BIG-IP DO disables DHCP for management routes. If you configure BIG-IP DO to preserve management routes, DHCP for management routes remains enabled. + +See |sysclass| for more information and BIG-IP DO usage. + + +.. literalinclude:: ../../examples/preserveOrigDhcpRoutes.json + :language: json + +| + +.. _manipfwr: + +Configuring firewall rules on the management interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for configuring firewall rules on the management interface is available in BIG-IP DO 1.24 and later. |br| If using BIG-IP 13.1, you must have the AFM module licensed and provisioned + +This example shows how you can configure firewall rules on the management interface in a BIG-IP DO declaration. If you are deploying on BIG-IP 13.1-13.x, you must have the AFM module licensed and provisioned. BIG-IP versions 14.1 and later do not have this requirement. + +This feature uses the new |manfw| class, which includes the |manfwr| settings. + +For more detail on Firewall rules and manual configuration instructions, see |fwkb| on AskF5. + +For more information and BIG-IP DO usage on individual properties, see |manfw| and |manfwr|. + +.. literalinclude:: ../../examples/managementIpFirewall.json + :language: json + + +| + +.. _routes: + +Configuring routes and managementRoutes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +These examples show how you can create routes and management routes in BIG-IP Declarative Onboarding declarations. BIG-IP DO has supported these objects, however an issue existed in BIG-IP DO prior to v1.23 that would not allow a type of **interface** on Management routes. + +See |route| and |manroute| in the Schema Reference for BIG-IP DO usage and options. + +The following examples contain route configuration, but no other BIG-IP DO configuration. You can use these classes as a part of a larger BIG-IP Declarative Onboarding declaration. + + +.. literalinclude:: ../../examples/routeInterface.json + :language: json + +| + +.. literalinclude:: ../../examples/managementRouteInterface.json + :language: json + +| + +.. _routeal: + +Configuring routing access lists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can create network routing access lists using BIG-IP Declarative Onboarding 1.24 and later. These access lists are a part of a larger BGP configuration, and enable you to specify allow and deny actions for source and destination addresses (or ranges). + +See |accesslist| and |accessentry| in the Schema Reference for BIG-IP DO usage and options. + +The following example contains multiple access lists, but no other BIG-IP DO configuration. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + + +.. literalinclude:: ../../examples/routingAccessList.json + :language: json + +| + +.. _vxlan: + +Configuring VXLAN tunnels +^^^^^^^^^^^^^^^^^^^^^^^^^ +This example shows how you can create VXLAN tunnels using BIG-IP Declarative Onboarding 1.25 and later. + +Virtual eXtended LAN (VXLAN) is a network virtualization scheme that overlays Layer 2 over Layer 3. VLXAN uses Layer 3 multicast to support the transmission of multicast and broadcast traffic in the virtual network, while decoupling the virtualized network from the physical infrastructure. See |vxlant| for more information and manual configuration. + +.. IMPORTANT:: In BIG-IP DO 1.36 and later, when creating a VXLAN Tunnel, the **acceptIpOptions** property in the TraffficControls class no longer automatically to true. Instead it will remain the same or be set to the value in the declaration. See |tcref| for more information about Traffic Control and acceptIpOptions. Also see the :ref:`Traffic Control example` on this page. + +See |tunnel| in the Schema Reference for BIG-IP DO usage and options. + +The following example contains a VXLAN tunnel, but no other BIG-IP DO configuration. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + + +.. literalinclude:: ../../examples/vxlanTunnel.json + :language: json + +| + +.. _mandhcp: + +Enabling management DHCP in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: + + Support for enabling management DHCP is available in BIG-IP DO 1.28 and later. + +This example shows how you can explicitly enable or disable DHCP for management IP addresses and routes in the |sysclass| class using the new **mgmtDhcpEnabled** property in BIG-IP DO 1.28 and later. + +This property is associated with the **preserveOrigDhcpRoutes** property, which provides the ability to preserve those DHCP routes (see the :ref:`Preserve DHCP routes` example on this page). + +.. IMPORTANT:: When you use both **mgmtDhcpEnabled** and **preserveOrigDhcpRoutes**, the values MUST match. + +See |sysclass| for more information and BIG-IP DO usage. + + +.. literalinclude:: ../../examples/mgmtDhcpEnabled.json + :language: json + +| + + + + + + +.. |br| raw:: html + +
+ +.. |rddoc| raw:: html + + Route Domain documentation + +.. |dagdoc| raw:: html + + Disaggregation DAG modes + +.. |snmpdoc| raw:: html + + Monitoring BIG-IP System Traffic with SNMP + +.. |tcref| raw:: html + + TrafficControl Class + +.. |loref| raw:: html + + RemoteAuthRole Class + + +.. |rolesdoc| raw:: html + + Remote User Account Management + +.. |lineorder| raw:: html + + Line Order + +.. |sldocs| raw:: html + + External Monitoring + +.. |slkb| raw:: html + + Configuring remote logging + +.. |slref| raw:: html + + SyslogRemoteServer Class + +.. |cmpdocs| raw:: html + + Additional VLAN Configuration Options + +.. |cmpref| raw:: html + + VLAN Class + +.. |trunkdoc| raw:: html + + Trunk documentation + +.. |trunkref| raw:: html + + Trunk class + +.. |sshd| raw:: html + + SSHD + +.. |httpd| raw:: html + + HTTPD + +.. |sysclass| raw:: html + + System + +.. |certclass| raw:: html + + DeviceCertificate + +.. |certdoc| raw:: html + + Updating a self-signed SSL device certificate on a BIG-IP system + +.. |controls| raw:: html + + Device_Controls + +.. |auth| raw:: html + + Authentication + +.. |k15000| raw:: html + + K15000 + +.. |auditlog| raw:: html + + Audit Logging documentation + +.. |macm| raw:: html + + Mac_Masquerade + +.. |mmkb| raw:: html + + K13502: Configuring MAC masquerade + +.. |vlanfs| raw:: html + + K13297: Overview of VLAN failsafe + +.. |dnsresolver| raw:: html + + DNS_Resolver + + +.. |dnsdoc| raw:: html + + BIG-IP DNS documentation + +.. |tunnel| raw:: html + + Tunnel + +.. |tg| raw:: html + + TrafficGroup + +.. |tgdoc| raw:: html + + BIG-IP Device Service Clustering: Administration + +.. |hagroup| raw:: html + + BIG-IP documentation + +.. |failover| raw:: html + + Failover documentation + +.. |unicast| raw:: html + + FailoverUnicast + +.. |route| raw:: html + + Route + +.. |mirrorkb| raw:: html + + Overview of connection and persistence mirroring + +.. |mirrorref| raw:: html + + MirrorIp + +.. |prefix| raw:: html + + RoutingPrefixList + +.. |prefixentry| raw:: html + + RoutingPrefixList-Entries + +.. |bgpvid| raw:: html + + BGP overview + +.. |routingbgp| raw:: html + + RoutingBGP + +.. |routingaspath| raw:: html + + RoutingAsPath + +.. |routemap| raw:: html + + RouteMap + +.. |afmdocs| raw:: html + + AFM documentation + +.. |fwp| raw:: html + + FirewallPolicy + + +.. |fwal| raw:: html + + FirewallAddressList + +.. |fwpl| raw:: html + + FirewallPortList + +.. |dnsresolverdocs| raw:: html + + Network Firewall documentation + +.. |alh| raw:: html + + Overview of the Auto Last Hop setting + +.. |mr| raw:: html + + Management Route class + +.. |bc| raw:: html + + Base Components + +.. |mip| raw:: html + + ManagementIp + +.. |ebgp| raw:: html + + RoutingBGP_neighbors + +.. |manfwr| raw:: html + + ManagementIpFirewall_rules + +.. |manfw| raw:: html + + ManagementIpFirewall + +.. |fwkb| raw:: html + + Restrict access to the BIG-IP management interface using network firewall rules + +.. |accesslist| raw:: html + + RoutingAccessList + +.. |accessentry| raw:: html + + RoutingAccessList-Entries + +.. |manroute| raw:: html + + ManagementRoute + +.. |vxlant| raw:: html + + Configuring Network Virtualization Tunnels diff --git a/docs/declarations/observability.rst b/docs/declarations/observability.rst new file mode 100644 index 00000000..7176f9bc --- /dev/null +++ b/docs/declarations/observability.rst @@ -0,0 +1,122 @@ +.. _observe-examples: + +Observability Examples +----------------------- +This section contains examples concerning observability (such as logging). + +.. _avrstream: + + +Creating an Analytics profile to enable AVR data streaming +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we are licensing a new BIG-IP, provisioning AVR, and creating an Analytics profile (you must have AVR provisioned to create an Analytics profile). This allows you to stream AVR data for consumption by F5 Telemetry Steaming or similar applications. + +.. literalinclude:: ../../examples/avrStreamingSupport.json + :language: json + :emphasize-lines: 17, 19-29 + + +:ref:`Back to top` + +| + +.. _snmp: + +Configuring SNMP in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to configure SNMP in a BIG-IP Declarative Onboarding declaration. You can use BIG-IP DO to configure SNMP agents, users, communities, trap events, and trap destinations. See the |snmpdoc| in the BIG-IP documentation for specific information. + +BIG-IP DO 1.32 and later add the ability to enable or disable **snmpd** daemon support of snmpV1 and snmpV2c queries using the **snmpV1** and **snmpV2c** properties in the SNMP class. Using a value of **true** (default) enables support, **false** disables support. + +In the following declaration snippet we show only the classes related to SNMP. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +**Important**: If you try to use this declaration with a BIG-IP DO version prior to 1.32, it will fail. Either upgrade BIG-IP DO to 1.32, or remove the snmpV1 and snmpV2c lines (highlighted in yellow). + +.. literalinclude:: ../../examples/snmp.json + :language: json + :emphasize-lines: 19, 20 + + +:ref:`Back to top` + +| + +.. _syslogdest: + +Configuring a System Log (syslog) Destination in declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how to configure a syslog destination using the **SyslogRemoteServer** class. For information on syslog destinations, see |sldocs| and the |slkb| Knowledge Base article. Also see |slref| in the Schema reference for usage options. + +**Important**: The remote syslog server must be accessible from your BIG-IP system on the default route domain (Domain 0) or management network, and conversely, your BIG-IP system is accessible from the remote syslog server. + +In the following declaration snippet we show only the SyslogRemoteServer class. You can use this class as a part of a larger BIG-IP Declarative Onboarding declaration. + +.. literalinclude:: ../../examples/syslogDestination.json + :language: json + +:ref:`Back to top` + +| + +.. _example20: + +Configuring Audit Logging in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure audit logging in the System class of a BIG-IP Declarative Onboarding declaration. This allows audit logging to start as early as possible. + +See |sysclass| in the Schema Reference for BIG-IP DO usage and options. For detailed information about audit logging on the BIG-IP, see the |auditlog|. + +.. IMPORTANT:: **guiAuditLog** is only available on TMOS v14.0 and later + + +.. literalinclude:: ../../examples/auditLogging.json + :language: json + +:ref:`Back to top` + +| + +.. _secanalytics: + +Configuring Security Analytics in a declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In this example, we show how you can configure security analytics in a BIG-IP Declarative Onboarding declaration. This allows you to gather analytics specific to security features, such as Denial of Service and Firewall ACL statistics. + +For a complete list of properties as well as DO usage, see |secana| in the Schema Reference. + + +.. literalinclude:: ../../examples/securityAnalytics.json + :language: json + +:ref:`Back to top` + +| + +.. |snmpdoc| raw:: html + + Monitoring BIG-IP System Traffic with SNMP + +.. |auditlog| raw:: html + + Audit Logging documentation + +.. |sysclass| raw:: html + + System + +.. |slkb| raw:: html + + Configuring remote logging + +.. |slref| raw:: html + + SyslogRemoteServer Class + +.. |sldocs| raw:: html + + External Monitoring + +.. |secana| raw:: html + + SecurityAnalytics Class + \ No newline at end of file diff --git a/docs/declarations/trace-response.json b/docs/declarations/trace-response.json new file mode 100644 index 00000000..99cef5d0 --- /dev/null +++ b/docs/declarations/trace-response.json @@ -0,0 +1,688 @@ +{ + "id": "e34cd96e-a1dc-4432-9efa-ff687e09117f", + "selfLink": "https://localhost/mgmt/shared/declarative-onboarding/task/e34cd96e-a1dc-4432-9efa-ff687e09117f", + "result": { + "class": "Result", + "code": 200, + "status": "OK", + "message": "success" + }, + "declaration": { + "schemaVersion": "1.15.0", + "class": "Device", + "async": true, + "webhook": "https://example.com/myHook", + "label": "my BIG-IP declaration for declarative onboarding", + "controls": { + "trace": true, + "traceResponse": true + }, + "Common": { + "class": "Tenant", + "mySystem": { + "class": "System", + "hostname": "bigip.example.com", + "cliInactivityTimeout": 1200, + "consoleInactivityTimeout": 1200, + "autoPhonehome": false + } + } + }, + "traces": { + "desired": { + "Common": { + "System": { + "hostname": "bigip.example.com", + "cliInactivityTimeout": 1200, + "consoleInactivityTimeout": 1200, + "autoPhonehome": false + }, + "DNS": { + "nameServers": [ + "172.27.1.1" + ], + "search": [ + "localhost" + ] + }, + "NTP": { + "timezone": "America/Los_Angeles" + }, + "Provision": { + "afm": "none", + "am": "none", + "apm": "none", + "asm": "none", + "avr": "none", + "cgnat": "none", + "dos": "none", + "fps": "none", + "gtm": "none", + "ilx": "none", + "lc": "none", + "ltm": "nominal", + "pem": "none", + "sslo": "none", + "swg": "none", + "urldb": "none" + }, + "VLAN": {}, + "DNS_Resolver": { + "f5-aws-dns": { + "name": "f5-aws-dns", + "answerDefaultZones": false, + "cacheSize": 5767168, + "randomizeQueryNameCase": true, + "routeDomain": "0", + "useIpv4": true, + "useIpv6": true, + "useTcp": true, + "useUdp": true, + "forwardZones": [ + { + "name": "amazonaws.com", + "nameservers": [ + { + "name": "8.8.8.8:53" + } + ] + }, + { + "name": "idservice.net", + "nameservers": [ + { + "name": "8.8.8.8:53" + } + ] + } + ] + } + }, + "Trunk": {}, + "SelfIp": {}, + "Route": {}, + "ConfigSync": { + "configsyncIp": "none" + }, + "FailoverUnicast": { + "unicastAddress": "none" + }, + "ManagementRoute": { + "default": { + "name": "default", + "mtu": 0, + "network": "default", + "gw": "10.145.127.254" + } + }, + "RouteDomain": { + "0": { + "name": "0", + "connectionLimit": 0, + "id": 0, + "strict": true, + "vlans": [ + "/Common/http-tunnel", + "/Common/socks-tunnel", + "/Common/external", + "/Common/internal" + ] + } + }, + "Authentication": { + "fallback": false, + "enabledSourceType": "local", + "remoteUsersDefaults": { + "role": "no-access", + "partitionAccess": "all", + "terminalAccess": "disabled" + } + }, + "RemoteAuthRole": {}, + "SnmpAgent": { + "contact": "Customer Name ", + "location": "Network Closet 1", + "allowList": [ + "192.0.2.0/8" + ] + }, + "SnmpTrapEvents": { + "device": true, + "authentication": false, + "agentStartStop": true + }, + "SnmpUser": {}, + "SnmpCommunity": { + "comm-public": { + "name": "public", + "access": "ro", + "ipv6": false, + "source": "default" + } + }, + "SnmpTrapDestination": {}, + "DagGlobals": { + "icmpHash": "icmp", + "roundRobinMode": "global", + "ipv6PrefixLength": 128 + }, + "TrafficControl": { + "acceptIpOptions": false, + "acceptIpSourceRoute": false, + "allowIpSourceRoute": false, + "continueMatching": false, + "maxIcmpRate": 100, + "maxRejectRate": 250, + "maxRejectRateTimeout": 30, + "minPathMtu": 296, + "pathMtuDiscovery": true, + "portFindThresholdTimeout": 30, + "portFindThresholdTrigger": 8, + "portFindThresholdWarning": true, + "rejectUnmatched": true, + "maxPortFindLinear": 16, + "maxPortFindRandom": 16 + }, + "HTTPD": { + "allow": [ + "All" + ], + "authPamIdleTimeout": 1200, + "maxClients": 10, + "sslCiphersuite": [ + "ECDHE-RSA-AES128-GCM-SHA256", + "ECDHE-RSA-AES256-GCM-SHA384", + "ECDHE-RSA-AES128-SHA", + "ECDHE-RSA-AES256-SHA", + "ECDHE-RSA-AES128-SHA256", + "ECDHE-RSA-AES256-SHA384", + "ECDHE-ECDSA-AES128-GCM-SHA256", + "ECDHE-ECDSA-AES256-GCM-SHA384", + "ECDHE-ECDSA-AES128-SHA", + "ECDHE-ECDSA-AES256-SHA", + "ECDHE-ECDSA-AES128-SHA256", + "ECDHE-ECDSA-AES256-SHA384", + "AES128-GCM-SHA256", + "AES256-GCM-SHA384", + "AES128-SHA", + "AES256-SHA", + "AES128-SHA256", + "AES256-SHA256" + ], + "sslProtocol": "all -SSLv2 -SSLv3 -TLSv1" + }, + "SSHD": { + "inactivityTimeout": 0 + }, + "Tunnel": { + "http-tunnel": { + "name": "http-tunnel", + "mtu": 0, + "usePmtu": true, + "autoLastHop": "default", + "tunnelType": "tcp-forward", + "typeOfService": "preserve" + }, + "socks-tunnel": { + "name": "socks-tunnel", + "mtu": 0, + "usePmtu": true, + "autoLastHop": "default", + "tunnelType": "tcp-forward", + "typeOfService": "preserve" + } + }, + "TrafficGroup": { + "traffic-group-1": { + "name": "traffic-group-1", + "autoFailbackEnabled": "false", + "autoFailbackTime": 60, + "failoverMethod": "ha-order", + "haLoadFactor": 1 + }, + "traffic-group-local-only": { + "name": "traffic-group-local-only", + "autoFailbackEnabled": "false", + "autoFailbackTime": 60, + "failoverMethod": "ha-order", + "haLoadFactor": 1 + } + } + }, + "parsed": true + }, + "current": { + "parsed": true, + "Common": { + "System": { + "consoleInactivityTimeout": 1200, + "hostname": "bigip.example.com", + "guiAuditLog": false, + "cliInactivityTimeout": 1200, + "tmshAuditLog": true, + "autoCheck": true, + "autoPhonehome": false + }, + "Provision": { + "afm": "none", + "am": "none", + "apm": "none", + "asm": "none", + "avr": "none", + "cgnat": "none", + "dos": "none", + "fps": "none", + "gtm": "none", + "ilx": "none", + "lc": "none", + "ltm": "nominal", + "pem": "none", + "sslo": "none", + "swg": "none", + "urldb": "none" + }, + "NTP": { + "timezone": "America/Los_Angeles" + }, + "DNS": { + "nameServers": [ + "172.27.1.1" + ], + "search": [ + "localhost" + ] + }, + "DNS_Resolver": { + "f5-aws-dns": { + "name": "f5-aws-dns", + "answerDefaultZones": false, + "cacheSize": 5767168, + "randomizeQueryNameCase": true, + "routeDomain": "0", + "useIpv4": true, + "useIpv6": true, + "useTcp": true, + "useUdp": true, + "forwardZones": [ + { + "name": "amazonaws.com", + "nameservers": [ + { + "name": "8.8.8.8:53" + } + ] + }, + { + "name": "idservice.net", + "nameservers": [ + { + "name": "8.8.8.8:53" + } + ] + } + ] + } + }, + "Trunk": {}, + "VLAN": { + "external": { + "name": "external", + "cmpHash": "default", + "failsafeAction": "failover-restart-tm", + "failsafeTimeout": 90, + "mtu": 1500, + "tag": 4094, + "failsafeEnabled": false, + "interfaces": [ + { + "name": "1.1", + "tagged": false + } + ] + }, + "internal": { + "name": "internal", + "cmpHash": "default", + "failsafeAction": "failover-restart-tm", + "failsafeTimeout": 90, + "mtu": 1500, + "tag": 4093, + "failsafeEnabled": false, + "interfaces": [ + { + "name": "1.2", + "tagged": false + } + ] + } + }, + "SelfIp": { + "external-self": { + "name": "external-self", + "address": "10.20.0.100/24", + "trafficGroup": "traffic-group-local-only", + "vlan": "external", + "allowService": "none" + }, + "internal-self": { + "name": "internal-self", + "address": "10.10.0.100/24", + "trafficGroup": "traffic-group-local-only", + "vlan": "internal", + "allowService": "default" + } + }, + "Route": {}, + "ConfigSync": { + "configsyncIp": "none" + }, + "FailoverUnicast": { + "addressPorts": "none" + }, + "TrafficGroup": { + "traffic-group-1": { + "name": "traffic-group-1", + "autoFailbackEnabled": "false", + "autoFailbackTime": 60, + "failoverMethod": "ha-order", + "haLoadFactor": 1 + }, + "traffic-group-local-only": { + "name": "traffic-group-local-only", + "autoFailbackEnabled": "false", + "autoFailbackTime": 60, + "failoverMethod": "ha-order", + "haLoadFactor": 1 + } + }, + "MAC_Masquerade": { + "traffic-group-1": { + "mac": "none", + "trafficGroup": "traffic-group-1" + }, + "traffic-group-local-only": { + "mac": "none", + "trafficGroup": "traffic-group-local-only" + } + }, + "ManagementRoute": { + "default": { + "name": "default", + "mtu": 0, + "network": "default", + "gw": "10.145.127.254" + } + }, + "SyslogRemoteServer": {}, + "Authentication": { + "fallback": false, + "enabledSourceType": "local", + "remoteUsersDefaults": { + "role": "no-access", + "partitionAccess": "all", + "terminalAccess": "disabled" + } + }, + "RouteDomain": { + "0": { + "name": "0", + "connectionLimit": 0, + "id": 0, + "strict": true, + "vlans": [ + "/Common/http-tunnel", + "/Common/socks-tunnel", + "/Common/external", + "/Common/internal" + ] + } + }, + "RemoteAuthRole": {}, + "SnmpTrapEvents": { + "device": true, + "authentication": false, + "agentStartStop": true + }, + "SnmpTrapDestination": {}, + "SnmpAgent": { + "contact": "Customer Name ", + "location": "Network Closet 1", + "allowList": [ + "192.0.2.1/8" + ] + }, + "SnmpUser": {}, + "SnmpCommunity": { + "comm-public": { + "name": "public", + "access": "ro", + "ipv6": false, + "source": "default" + } + }, + "DagGlobals": { + "icmpHash": "icmp", + "roundRobinMode": "global", + "ipv6PrefixLength": 128 + }, + "HTTPD": { + "allow": [ + "All" + ], + "authPamIdleTimeout": 1200, + "maxClients": 10, + "sslCiphersuite": [ + "ECDHE-RSA-AES128-GCM-SHA256", + "ECDHE-RSA-AES256-GCM-SHA384", + "ECDHE-RSA-AES128-SHA", + "ECDHE-RSA-AES256-SHA", + "ECDHE-RSA-AES128-SHA256", + "ECDHE-RSA-AES256-SHA384", + "ECDHE-ECDSA-AES128-GCM-SHA256", + "ECDHE-ECDSA-AES256-GCM-SHA384", + "ECDHE-ECDSA-AES128-SHA", + "ECDHE-ECDSA-AES256-SHA", + "ECDHE-ECDSA-AES128-SHA256", + "ECDHE-ECDSA-AES256-SHA384", + "AES128-GCM-SHA256", + "AES256-GCM-SHA384", + "AES128-SHA", + "AES256-SHA", + "AES128-SHA256", + "AES256-SHA256" + ], + "sslProtocol": "all -SSLv2 -SSLv3 -TLSv1" + }, + "TrafficControl": { + "acceptIpOptions": false, + "acceptIpSourceRoute": false, + "allowIpSourceRoute": false, + "continueMatching": false, + "maxIcmpRate": 100, + "maxRejectRate": 250, + "maxRejectRateTimeout": 30, + "minPathMtu": 296, + "pathMtuDiscovery": true, + "portFindThresholdTimeout": 30, + "portFindThresholdTrigger": 8, + "portFindThresholdWarning": true, + "rejectUnmatched": true, + "maxPortFindLinear": 16, + "maxPortFindRandom": 16 + }, + "SSHD": { + "allow": [ + "ALL" + ], + "inactivityTimeout": 0 + }, + "Tunnel": { + "http-tunnel": { + "name": "http-tunnel", + "mtu": 0, + "usePmtu": true, + "autoLastHop": "default", + "tunnelType": "tcp-forward", + "typeOfService": "preserve" + }, + "socks-tunnel": { + "name": "socks-tunnel", + "mtu": 0, + "usePmtu": true, + "autoLastHop": "default", + "tunnelType": "tcp-forward", + "typeOfService": "preserve" + } + }, + "Disk": { + "applicationData": 26128384 + } + } + }, + "diff": [ + { + "kind": "D", + "path": [ + "Common", + "System", + "guiAuditLog" + ], + "lhs": false + }, + { + "kind": "D", + "path": [ + "Common", + "System", + "tmshAuditLog" + ], + "lhs": true + }, + { + "kind": "D", + "path": [ + "Common", + "System", + "autoCheck" + ], + "lhs": true + }, + { + "kind": "D", + "path": [ + "Common", + "VLAN", + "external" + ], + "lhs": { + "name": "external", + "cmpHash": "default", + "failsafeAction": "failover-restart-tm", + "failsafeTimeout": 90, + "mtu": 1500, + "tag": 4094, + "failsafeEnabled": false, + "interfaces": [ + { + "name": "1.1", + "tagged": false + } + ] + } + }, + { + "kind": "D", + "path": [ + "Common", + "VLAN", + "internal" + ], + "lhs": { + "name": "internal", + "cmpHash": "default", + "failsafeAction": "failover-restart-tm", + "failsafeTimeout": 90, + "mtu": 1500, + "tag": 4093, + "failsafeEnabled": false, + "interfaces": [ + { + "name": "1.2", + "tagged": false + } + ] + } + }, + { + "kind": "D", + "path": [ + "Common", + "SelfIp", + "external-self" + ], + "lhs": { + "name": "external-self", + "address": "10.20.0.100/24", + "trafficGroup": "traffic-group-local-only", + "vlan": "external", + "allowService": "none" + } + }, + { + "kind": "D", + "path": [ + "Common", + "SelfIp", + "internal-self" + ], + "lhs": { + "name": "internal-self", + "address": "10.10.0.100/24", + "trafficGroup": "traffic-group-local-only", + "vlan": "internal", + "allowService": "default" + } + }, + { + "kind": "D", + "path": [ + "Common", + "FailoverUnicast", + "addressPorts" + ], + "lhs": "none" + }, + { + "kind": "N", + "path": [ + "Common", + "FailoverUnicast", + "unicastAddress" + ], + "rhs": "none" + }, + { + "kind": "D", + "path": [ + "Common", + "SSHD", + "allow" + ], + "lhs": [ + "ALL" + ] + }, + { + "kind": "D", + "path": [ + "Common", + "Disk" + ], + "lhs": { + "applicationData": 26128384 + } + } + ] + }, + "lastUpdate": "2020-08-24T16:44:41.140Z" + } \ No newline at end of file diff --git a/docs/do-container.rst b/docs/do-container.rst deleted file mode 100644 index d17416c5..00000000 --- a/docs/do-container.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _container: - -Using Declarative Onboarding in a Docker Container --------------------------------------------------- -F5 Networks has created a Docker Container (currently Community Supported) with Declarative Onboarding installed (1.2.0). You can use this container to create new BIG-IP systems. This can be extremely useful for automating BIG-IP configurations. - -.. IMPORTANT:: Note this solution is currently Community Supported and in the **f5Devcentral** organization on Docker Hub. Once it is fully supported by F5, it will move to **f5networks** on Docker Hub. - -Prerequisites -~~~~~~~~~~~~~ -1. You must have Docker installed (https://www.docker.com/get-started/) and running. -2. You must have a target BIG-IP system running version v13.1 or later to use Declarative Onboarding. -3. If running Docker on Microsoft Windows, you must make sure the drive in which you are working (for example, your C: drive) is shared in the Docker settings. -4. Once your container is running, you must use the **target** parameters in your Declarative Onboarding declaration as described on this page. - - -.. _test-container: - -Downloading and starting the Declarative Onboarding Docker container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first task is to download (pull) the Docker image from Docker Hub. If you plan on adding base authentication, see :ref:`base` for guidance on the directory structure for pulling the image. - -1. Download the F5 Declarative Onboarding Docker image using the following command syntax: ``docker pull f5devcentral/f5-do-container:``. The is optional and allows you to include a specific tag using : after f5-Declarative Onboarding-container. If you do not include a tag, it downloads the latest version (:latest). |br| Once the download is complete, you should see a status message stating the image was downloaded. - -2. Run Declarative Onboarding container using the command: ``docker run --name do_container --rm -d -p 8443:443 -p 8080:80 f5devcentral/f5-do-container:latest``. **--name do_container** is optional and can be changed to any name you want, it's just an easy way to identify this container. - -3. To test the Docker image is functional, you can use one of the following options (the following examples use **localhost**, you can use an IP address in place of localhost if your client and container are on different devices): - - - From your RESTful client, use **GET** to send ``https://localhost:8443/mgmt/shared/declarative-onboarding/example`` - - - Run the following cURL command: ``curl -k https://localhost:8443/mgmt/shared/declarative-onboarding/example`` - - -The system returns an example Declarative Onboarding declaration. - -| - -Sending a declaration to a BIG-IP using the Docker container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To send a declaration to a BIG-IP system you use the new *target* parameters in the Declarative Onboarding class (see the example below). These parameters specify the BIG-IP system where you want to send the configuration, and the user account with permission to access that BIG-IP system. - -Again, the following examples use **localhost**, you can use an IP address in place of localhost if your client and container are on different devices. - -To send a declaration with the container using a RESTful client, use ``https://localhost:8443/mgmt/shared/declarative-onboarding``, and then POST a declaration. - -To send a declaration with the container using cURL, use ``curl -sku admin:admin -H "Content-Type: application/json" -X POST https://localhost:8443/mgmt/shared/declarative-onboarding`` and then include the declaration. - - - -Example declaration snippet using a RESTful client -`````````````````````````````````````````````````` -To send a declaration from the container with a RESTful client like Postman, use the targetHost, targetUsername, and targetPassphrase parameters as shown in the following example (using values from your configuration). In this example, your declaration would continue after the last (schemaVersion) line. - -Additionally, see :doc:`json-pointers` for information on using JSON/Declarative Onboarding pointers in your declaration. - -.. code-block:: shell - :emphasize-lines: 3-7 - - { - - "class": "DO", - "targetHost": "192.0.2.76", - "targetPort": 8443, - "targetUsername": "admin", - "targetPassphrase": "myAdminPassword", - "declaration": { - "class": "Device", - "schemaVersion": "1.0.0", - ... - } - } - - - - - -**Container-specific parameters** - -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Parameter | Options | Required? | Description/Notes | -+====================+======================+===========+========================================================================================================================================================================================================================================================================================================================================+ -| targetHost | string | YES | IP address or host name of the target BIG-IP system to which you want to send the configuration. | -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| targetPort | integer | NO | TCP port number of management service on targetHost. If you do not specify a targetPort, Declarative Onboarding uses a default of 0, meaning it will auto-discover the target port. | -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| targetTokens | object | NO | One or more HTTP headers (each a property, like ‘X-F5-Auth-Token’: ‘MF6APSRUYKTMSDBEOOEWLCNSO2’) you want to send with queries to the targetHost management service as authentication/authorization tokens | -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| targetUsername | string | YES | Username of the principal authorized to modify configuration of targetHost (may not include the character ':'). NOTE: This is generally not required to configure 'localhost' because client authentication and authorization precede invocation of DO. It is also not required for any targetHost if you populate targetTokens. | -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| targetPassphrase | string | YES | Passphrase for targetUsername account. This is generally not required to configure 'localhost' and is not required when you populate targetTokens. | -+--------------------+----------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -| - -Example declaration snippet using cURL -`````````````````````````````````````` -To send a declaration from the container with cURL, use the same parameters as described in the preceding table. The rest of your declaration would continue after the last (schemaVersion) line. - -.. code-block:: shell - - curl -sku admin:admin -H "Content-Type: application/json" -X POST https://localhost:8443/mgmt/shared/declarative-onboarding -d ‘{ - "class": "DO", - "targetHost": "192.0.2.76", - "targetUsername": "admin", - "targetPassphrase": "admin", - "declaration": { - "class": "Device", - "schemaVersion": "1.0.0", - …}’ - - -.. _base: - -Adding Basic Authentication -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable Basic authentication, which allows you to protect your container running Declarative Onboarding, you can :guilabel:`COPY` or :guilabel:`MOUNT` the authentication configuration and user password files to your container using the following instructions. - -**Notes and requirements for adding Basic authentication** - -- You should be at least somewhat familiar with the Docker command line. -- You should have knowledge of Apache .htpasswd for adding Basic authentication. See the Apache documentation for details. -- While we include commands for Microsoft Windows in this section, getting paths and directories set up in Windows can be tricky, so we recommend using a Linux-based system to add Basic authentication. -- In our example, we are using a hashed value for the password *admin*. We strongly recommend you use a different password. Use an htpasswd generator to generate a value for a stronger password. - -| - - -1. Choose a local directory that will be mounted as a volume for the container to handle authentication. From that directory, pull the Declarative Onboarding image from Docker hub (see :ref:`test-container`) -2. Inside that root directory, create a new directory named **basic-auth**. You will create two sub-directories in this directory. If you want to use different names for your directories, you must modify the command to use the appropriate directories when you run the container. - - #. Inside the basic-auth directory you created, create a directory named **auth** directory. - #. In the **auth** directory, create a file named **basic.conf** with the following content:: - - AuthType basic - AuthName "private area" - AuthUserFile /etc/www/pass/.htpasswd-users - Require valid-user - - #. In the **basic-auth** directory, create another directory named **pass**. - #. In the **auth** directory, create a file named **.htpasswd-users** your user name and a hashed password. Again, this example uses *admin* for the password, use http://www.htaccesstools.com/htpasswd-generator/ to generate a hash for a stronger password.:: - - admin:$apr1$DTbcp1qi$vJ2AXcB.Ma8zznKJLEXKv. - -3. Run Declarative Onboarding container at the root directory. This maps the two directories you created to two directories inside the container for Apache. - - - If you are using a Linux-based system, use the following command: ``docker run -d -p 8443:443 -p 8080:80 -v `pwd`/basic-auth/auth/:/usr/local/apache2/conf/auth/ -v `pwd`/basic-auth/pass/:/etc/www/pass/ f5devcentral/f5-do-container`` - - - If you are using Windows, use the following command: ``docker run -d -p 8443:443 -p 8080:80 -v %cd%/basic-auth/auth/:/usr/local/apache2/conf/auth/ -v %cd%/basic-auth/pass/:/etc/www/pass/ f5devcentral/f5-do-container`` - - -4. Open your RESTful API client such as Postman, and log with the basic Auth you just configured, in our example, using **admin** for the username and password. - -5. Test your docker container to get info from BIG-IP using step 3 of :ref:`test-container`. - - - -.. _container-ex: - -Full declaration using the Declarative Onboarding container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example uses a simple example declaration using the container. - -.. literalinclude:: ../examples/viaASG.json - :language: json - - - - - - - - - - - - -.. |br| raw:: html - -
\ No newline at end of file diff --git a/docs/do-on-bigiq.rst b/docs/do-on-bigiq.rst index 5952dae9..4b85739d 100644 --- a/docs/do-on-bigiq.rst +++ b/docs/do-on-bigiq.rst @@ -1,20 +1,16 @@ .. _do-bigiq: -Using DO on BIG-IQ -================== -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: +Using BIG-IP DO on BIG-IQ +========================= +You can use the BIG-IP Declarative Onboarding endpoint on the BIG-IQ v7.0 and later to configure your BIG-IP devices. After you onboard the BIG-IPs using BIG-IP Declarative Onboarding, you can manage them from the BIG-IQ system, including using |as3|. - DO is available in BIG-IQ v7.0 and later +See |kb| for information on BIG-IQ Centralized Management compatibility with F5 BIG-IP Declarative Onboarding. -You can use the Declarative Onboarding endpoint on the BIG-IQ v7.0 and later to configure your BIG-IP devices. After you onboard the BIG-IPs using Declarative Onboarding, you can manage them from the BIG-IQ system, including using |as3|. +See the |bigiqdo| for information on BIG-IP DO and BIG-IQ. -See |kb| for information on BIG-IQ Centralized Management compatibility with F5 Declarative Onboarding. - -See the |bigiqdo| for information on DO and BIG-IQ. - -Verifying DO is installed on the BIG-IQ ---------------------------------------- -You can ensure DO is installed on the BIG-IQ device using the following methods: +Verifying BIG-IP DO is installed on the BIG-IQ +---------------------------------------------- +You can ensure BIG-IP DO is installed on the BIG-IQ device using the following methods: - From your RESTful client, after entering your credentials, use **GET** to send |br| ``https://(IP address of BIG-IQ)/mgmt/shared/declarative-onboarding/info`` @@ -48,114 +44,17 @@ You can also GET to send ``https://(IP address of BIG-IQ)/mgmt/shared/declarativ .. _do-bigiq-table: -Sending a DO declaration to BIG-IQ ----------------------------------- -The request to send a Declarative Onboarding declaration to BIG-IQ is the same as the request for BIG-IP, just the IP address is different: |br| +Sending a BIG-IP DO declaration to BIG-IQ +----------------------------------------- +The request to send a BIG-IP Declarative Onboarding declaration to BIG-IQ is the same as the request for BIG-IP, just the IP address is different: |br| ``https://(IP address of BIQ-IP)/mgmt/shared/declarative-onboarding/info`` -The JSON in the body of the POST request can includes the following parameters. See :ref:`bigiqdo1` an example declaration for using DO on BIG-IQ. - -.. list-table:: - :widths: 20 20 20 40 - :header-rows: 1 - - * - Name - - Type - - Required - - Description - * - class - - string - - True - - "DO" - * - bigIqSettings - - object - - True - - Settings for the BIG-IQ performing onboarding - * - *accessModuleProperties* - - string - - Yes if an APM module is being imported - - Additional access module properties provided for the import. - * - *clusterName* - - string - - True if the BIG-IP is to be managed as part of a cluster - - Cluster display name of the BIG-IP Device Service Clustering (DSC) group. `clusterName` must be the same for all the BIG-IPs in a DSC group. - * - *conflictPolicy* - - string - - True if `failImportOnConflict` is false. - - Conflict policy for the onboarding. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION” - * - *deployWhenDscChangesPending* - - string - - boolean - - Deploy when there are pending DSC changes on BIG-IP. - * - *deviceConflictPolicy* - - string - - False - - Conflict policy for device-specific objects. For Access, a device-specific import can accept “USE_BIGIP” for all device-specific objects. Default is the same value as `conflictPolicy`. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION” - * - *failImportOnConflict* - - boolean - - False - - True specifies to fail import task if there are conflicts. This can true if you want to resolve the conflicts manually. Default is false. - * - *snapshotWorkingConfig* - - boolean - - False - - True specifies a snapshot of the working configuration for current BIG-IPs before the import. Default is false. - * - *statsConfig* - - object - - False - - Stats configuration details for the BIG-IP - * - *enabled* - - boolean - - True `statsConfig` if is defined - - True enables collecting statistics for the BIG-IP - * - *zone* - - string - - False - - User-defined names that associate BIG-IPs with one or more data collection device (DCD) systems to provide optimal routing for statistics traffic. This value can be “default”. - * - *useBigiqSync* - - boolean - - False - - True to use BIG-IQ to push changes to cluster BIG-IPs instead of using the BIG-IP cluster sync to synchronize configuration. - * - *versionedConflictPolicy* - - string - - False - - Conflict policy for version-specific objects. For Access, a device-specific import can accept “USE_BIGIP” for all device-specific objects. Default is the same value as `conflictPolicy`. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ”, “KEEP_VERSION” - * - declaration - - object - - True - - The Declarative Onboarding declaration that you want to transmit. The DO declaration includes the BIG-IP objects you want the system to configure. - * - *async* - - boolean - - True - - The `async` field must be true to use DO on BIG-IQ. - * - *Common* - - object - - True - - Sections of the DO declaration. - * - *admin* - - object - - True - - The `admin` section of `Common` in the DO declaration is required if making an AWS initial declaration using the `targetSshKey`. - * - targetHost - - string - - True - - IP address of the onboarding BIG-IP. Required for the initial or subsequent onboardings of a BIG-IP. - * - targetPassphrase - - string - - True - - Admin password of the onboarding BIG-IP. Required for the initial or subsequent onboarding of a BIG-IP in Azure or VMware environment. You must specify a `targetUsername` or `targetSshKey` when using an Azure or VMware environment. Not required for onboarding BIG-IP VEs in AWS cloud, if you have specified `targetSshKey`. - * - targetSshKey - - object - - False - - Required for initial onboarding of a new BIG-IP VE in an AWS cloud. Use `targetPassphrase` for any subsequent onboarding of the same BIG-IP VE on AWS. `targetSshKey` is not used in Azure and VMware environments, those environments alway use `targetUsername` and `targetPassphrase`. - * - *path* - - string - - False - - Path to ssh key. - * - targetUsername - - string - - True - - Admin user name of the onboarding BIG-IP. Required for the initial or subsequent onboardings of a BIG-IP. +The JSON in the body of the POST request can include the parameters in the |bigiqapi| in the BIG-IQ API documentation. + +See :ref:`bigiqdo1` an example declaration for using BIG-IP DO on BIG-IQ. + + .. |kb| raw:: html @@ -174,6 +73,8 @@ The JSON in the body of the POST request can includes the following parameters. BIG-IQ API documentation +.. |bigiqapi| raw:: html + BIG-IP DO/BIG-IQ parameter table diff --git a/docs/examples.rst b/docs/examples.rst index 4ea6d998..cfe0e080 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,44 +1,96 @@ -.. _examples: - -Example declarations +Example Declarations ==================== -The following examples show you some Declarative Onboarding declarations. +This section contains a number of additional example declarations you can use. Use the following index, or the links on the right to go to a specific category of declaration. + +The following categories were introduced with the release of BIG-IP DO 1.17. .. IMPORTANT:: The following examples include passwords that may not be valid for BIG-IP v14.0 and later. See |pass| for specific requirements. +.. NOTE:: All of the examples will work on BIG-IP and BIG-IQ, however, when using BIG-IP DO on a BIG-IQ, you must add the BIG-IQ section to the declaration (see :doc:`do-on-bigiq` and the :ref:`BIG-IQ examples` for details). + + +Basic Examples +-------------- + +.. toctree:: + :maxdepth: 2 + :includehidden: + :glob: + + declarations/basic + +Network Objects +--------------- + +.. toctree:: + :maxdepth: 2 + :includehidden: + :glob: + + declarations/network-objects + +Clustering +---------- + +.. toctree:: + :maxdepth: 2 + :includehidden: + :glob: + + declarations/clustering -BIG-IP and general example declarations ---------------------------------------- +Authentication +-------------- .. toctree:: :maxdepth: 2 :includehidden: :glob: - bigip-examples + declarations/auth +Observability +------------- + +.. toctree:: + :maxdepth: 2 + :includehidden: + :glob: -BIG-IQ and general example declarations ---------------------------------------- + declarations/observability + +BIG-IQ Examples +--------------- .. toctree:: :maxdepth: 2 :includehidden: :glob: - bigiq-examples + declarations/bigiq-examples +GSLB Examples +------------- -Container example declarations ------------------------------- +.. toctree:: + :maxdepth: 2 + :includehidden: + :glob: + + declarations/gslb + +Miscellaneous +------------- .. toctree:: :maxdepth: 2 :includehidden: :glob: - container-examples + declarations/miscellaneous + + .. |pass| raw:: html diff --git a/docs/faq.rst b/docs/faq.rst index dd0fd74f..930e04ec 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,11 +1,11 @@ -Declarative Onboarding FAQ --------------------------- +Frequently Asked Questions (FAQ) +-------------------------------- The following are frequently asked questions for Declarative Onboarding. **What is Declarative Onboarding?** -F5 Declarative Onboarding (DO) is an F5 offering that provides a simple and consistent way to automate BIG-IP onboarding via Declarative REST APIs. A brother to |AS3|, DO provides a sustainable foundation to enable F5’s Infrastructure as Code (IaC) strategy. DO automates L1-L3 on-boarding for BIG-IP, making BIG-IP available on the network and ready to accept L4-L7 Application Services configurations. +F5 Declarative Onboarding (DO) is an F5 offering that provides a simple and consistent way to automate BIG-IP onboarding via Declarative REST APIs. A brother to |AS3|, DO provides a sustainable foundation to enable F5’s Infrastructure as Code (IaC) strategy. DO automates L1-L3 on-boarding for BIG-IP, making BIG-IP available on the network and ready to accept L4-L7 Application Services configurations. For more information, return to :doc:`index` @@ -15,7 +15,6 @@ For more information, return to :doc:`index` The DO Extension is available |dl|. See :doc:`installation` for instructions. -The DO Container is available on |docker|. | @@ -27,20 +26,11 @@ Yes. See the |support| to see the versions of DO that are currently supported. **What is the "DO Container"? Is it Supported?** -- This is a Docker container form-factor for DO 1.2+ for off-box deployments. -- Provides flexibility to deploy DO via any container management platform -- Ongoing container optimization for DO; separate from F5 API Services Gateway: - - - The DO Container is specifically for DO use cases, - - F5 API Services Gateway is specifically for custom iControl LX extension use cases (and is community-supported) - -The DO container is currently Community Supported and in the F5Devcentral organization on Docker Hub. Once it is fully supported by F5, it will move to **f5networks** on Docker Hub. - -See :doc:`do-container` for more information. +The DO Container was a community-supported solution, and was deprecated in DO 1.16. F5 will no longer provide new versions of DO running in a container. | -**How is DO different from onboarding with Ansible?** +**How is DO different from onboarding with Ansible?** - Ansible is part of a large vendor ecosystem to manage and automate configuration of multiple platform types within the data center - Ansible automates via imperative YAML playbooks which require knowledge of which BIG-IP modules need to be run and in which order @@ -52,16 +42,16 @@ See the |ansible| for more information. | -**When is DO a good fit and when it is not?** +**When is DO a good fit and when it is not?** DO is a good fit where: - - Declarative interface is required to abstract away the complexity of BIG-IP onboarding + - Declarative interface is required to abstract away the complexity of BIG-IP onboarding - You need to onboard BIG-IP as Infrastructure as Code (IaC) via integration with DevOps pipelines -DO may not be a good fit where: +DO may not be a good fit where: - - You do not want to use a Declarative interface + - You do not want to use a Declarative interface - You are unwilling or unable to deploy iControl Extension RPM on BIG-IP - You require the BIG-IP to be the configuration source-of-truth - You want to continue using imperative interfaces to configure (not just monitor or troubleshoot) BIG-IP: @@ -72,12 +62,19 @@ DO may not be a good fit where: | - **Which TMOS versions does DO require?** + **Which TMOS versions does DO require?** DO requires TMOS 13.1+ | +**Does Declarative Onboarding support hardware platforms?** + +Declarative Onboarding is intended for use with Cloud and Virtual Edition images, but it will also run on and configure hardware platforms. +Features specific to hardware platforms, such as creating vCMP guests and setting TurboFlex profiles are not on the Declarative Onboarding roadmap. + +| + **What is a "DO Declaration"?** - DO uses a declarative model, meaning you provide a JSON declaration rather than a set of imperative commands @@ -89,22 +86,21 @@ DO requires TMOS 13.1+ **What is the VSCode DO Declaration Validator?** -This capability enables you to validate an DO declaration against the DO schema using Microsoft Visual Studio Code (VSCode) editor, and is useful when composing a declaration manually or to check the accuracy of a declaration prior to deployment +This capability enables you to validate an DO declaration against the DO schema using Microsoft Visual Studio Code (VSCode) editor, and is useful when composing a declaration manually or to check the accuracy of a declaration prior to deployment See :doc:`validate` for information. | -**Where can I find DO declaration examples? for licensing BIG-IP via BIG-IQ?** +**Where can I find DO declaration examples?** -- BIG-IP and general example declarations can be found :doc:`here`. -- BIG-IQ example declarations for licensing BIG-IP devices can be found :doc:`here`. +- You can find all DO example declarations, including those for BIG-IQ, here: :doc:`examples`. | **Does DO collect any usage data?** -The Declarative Onboarding (DO) Extension gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system’s phone home feature as described in |phone|. +The Declarative Onboarding (DO) Extension gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system's phone home feature as described in |phone|. | @@ -116,6 +112,28 @@ The API Contract for the F5 Automation Toolchain (Declarative Onboarding, AS3 an As of January 2020, no breaking changes have been made to AS3, Declarative Onboarding, or Telemetry Streaming since inception. None are anticipated at this time. A breaking change, if any, will be noted by a change to the major release number ("xx"). For example, the AS3 schema version would become "4.0.0." +| + +.. _cipher: + +**What are the values I can use for the HTTPD ciphersuite?** + +Prior to Declarative Onboarding 1.26, HTTPD ciphersuite values were contained in a static list with a limited number from which to choose. In DO 1.26 and later, we removed the enumerated list, and allow you to include any valid ciphersuite value. + +For a list of valid ciphersuite values, see https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslciphersuite. You can also see https://support.f5.com/csp/article/K86554600 for a list of SSL ciphers supported on BIG-IP platforms. + +| + +.. _apidoc: + +**Where can I find the API documentation?** + +You can find the API documentation here: |api| + + +.. |api| raw:: html + + API documentation .. |AS3| raw:: html @@ -131,9 +149,6 @@ As of January 2020, no breaking changes have been made to AS3, Declarative Onboa Release Asset on GitHub -.. |docker| raw:: html - - Docker Hub .. |support| raw:: html diff --git a/docs/http-methods.rst b/docs/http-methods.rst index 709e8b0b..80308e79 100644 --- a/docs/http-methods.rst +++ b/docs/http-methods.rst @@ -1,6 +1,6 @@ HTTP Methods ------------ -This section contains the current HTTP methods available with Declarative Onboarding. +This section contains the current HTTP methods available with BIG-IP Declarative Onboarding. POST @@ -12,11 +12,11 @@ echoes your declaration back to you. .. NOTE:: If you are using a single NIC BIG-IP system, you must include port 8443 after your IP address in your POST: **https://:8443/mgmt/shared/declarative-onboarding** -The first time you POST a Declarative Onboarding declaration, the system records the configuration that exists prior to processing the declaration. If you POST subsequent declarations to the same BIG-IP system, and leave out some of the properties you initially used, the system restores the original properties for those items. +The first time you POST a BIG-IP Declarative Onboarding declaration, the system records the configuration that exists prior to processing the declaration. If you POST subsequent declarations to the same BIG-IP system, and leave out some of the properties you initially used, the system restores the original properties for those items. .. _postnote: -**NOTE**: When using Declarative Onboarding 1.4.0 and later, the response to a POST includes additional fields that help handle onboarding multiple BIG-IP devices using the Container without waiting for previous declarations to finish onboarding. These fields are **id** and **selfLink**. For example, a POST using 1.4.0 returns the following: +**NOTE**: When using BIG-IP Declarative Onboarding 1.4.0 and later, the response to a POST includes additional fields that help identify asynchronous BIG-IP Declarative Onboarding tasks. These fields are **id** and **selfLink**. For example, a POST using 1.4.0 returns the following: .. code-block:: bash :emphasize-lines: 2-3 @@ -39,9 +39,9 @@ The first time you POST a Declarative Onboarding declaration, the system records GET ~~~ -You can use the GET method to retrieve the status of declarations you previously sent to Declarative Onboarding. Use the GET method to the URI +You can use the GET method to retrieve the status of declarations you previously sent to BIG-IP Declarative Onboarding. Use the GET method to the URI ``https:///mgmt/shared/declarative-onboarding``. Only declarations you create -in Declarative Onboarding return, GET does not return anything that was not created by Declarative Onboarding. +in BIG-IP Declarative Onboarding return, GET does not return anything that was not created by BIG-IP Declarative Onboarding. .. NOTE:: If you are using a single NIC BIG-IP system, you must include port 8443 after your IP address in your GET: **https://:8443/mgmt/shared/declarative-onboarding** @@ -52,11 +52,11 @@ GET query parameters .. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - **statusCodes** is available in DO v1.9.0 and later. + **statusCodes** is available in BIG-IP DO v1.9.0 and later. You can use the following optional URL query parameters with a GET request. -The statusCodes parameter is only available in DO 1.9.0 and later. +The statusCodes parameter is only available in BIG-IP DO 1.9.0 and later. +-------------------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Query Parameter | Options | Description/Notes | @@ -68,7 +68,7 @@ The statusCodes parameter is only available in DO 1.9.0 and later. **Examples** -- ``https://MGMT_IP/mgmt/shared/declarative-onboarding?show=full`` |br| DO returns the original and current configuration. +- ``https://MGMT_IP/mgmt/shared/declarative-onboarding?show=full`` |br| BIG-IP DO returns the original and current configuration. - ``https://MGMT_IP/mgmt/shared/declarative-onboarding?statusCodes=legacy`` |br| If there is an error, the GET response would return that error as the HTTP status, but the GET request itself would not error. - ``https://MGMT_IP/mgmt/shared/declarative-onboarding?statusCodes=experimental`` |br| Returns a 200 HTTP status code unless there is an issue with the request. The results contain the status. @@ -78,10 +78,10 @@ The statusCodes parameter is only available in DO 1.9.0 and later. Additional endpoints for GET ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Declarative Onboarding v1.4 introduced two new endpoints for the GET method +BIG-IP Declarative Onboarding v1.4 introduced two new endpoints for the GET method - ``/shared/declarative-onboarding/task`` with optional ``/`` - If you do not specify a taskId, DO returns an array of all tasks. If you use the taskId, DO returns the specific task. The response looks like that for the POST response. + If you do not specify a taskId, BIG-IP DO returns an array of all tasks. If you use the taskId, BIG-IP DO returns the specific task. The response looks like that for the POST response. For example, sending a GET to the **/task** endpoint looks like the following when the task is in progress: @@ -129,7 +129,7 @@ When the task has completed, you see the code, status and message change: | - ``/shared/declarative-onboarding/config/`` - Returns the original configuration of the specified device (identified by device machineId), or all devices if no machineId is given. This endpoint is for informational/debugging purposes only, and is not something you need in the day-to-day use of Declarative Onboarding. + Returns the original configuration of the specified device (identified by device machineId), or all devices if no machineId is given. This endpoint is for informational/debugging purposes only, and is not something you need in the day-to-day use of BIG-IP Declarative Onboarding. Example response from sending GET to /shared/declarative-onboarding/config: @@ -190,11 +190,7 @@ Example response from sending GET to /shared/declarative-onboarding/config: Using GET with the /inspect endpoint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. sidebar:: :fonticon:`fa fa-info-circle fa-lg` Version Notice: - - The **/inspect** endpoint for GET is available in DO v1.7.0 and later. - -In DO version 1.7.0 and later, you can use a GET request to the /inspect endpoint to retrieve the current BIG-IP configuration. This information can be used for modifying the DO declaration before the first POST. The response returns the classes that DO is aware of and their current state, in the format of a DO declaration. +In BIG-IP DO version 1.7.0 and later, you can use a GET request to the /inspect endpoint to retrieve the current BIG-IP configuration. This information can be used for modifying the BIG-IP DO declaration before the first POST. The response returns the classes BIG-IP DO is aware of and their current state, in the format of a BIG-IP DO declaration. The full endpoint is **https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect** @@ -214,9 +210,9 @@ You can use the following optional URL query parameters with a GET request to th **Examples** -- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect`` |br| DO will try to fetch configuration from localhost (allowed only when running on BIG-IP). -- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect?targetHost=X.X.X.X`` |br| DO will try to fetch configuration from host X.X.X.X, port 443 or 8443, username === admin and password === admin -- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect?targetHost=X.X.X.X&targetPort=443&targetUsername=ZZZ&targetPassword=AAA`` |br| DO will try to fetch configuration from host X.X.X.X, port 443, username === ZZZ and password === AAA +- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect`` |br| BIG-IP DO will try to fetch configuration from localhost (allowed only when running on BIG-IP). +- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect?targetHost=X.X.X.X`` |br| BIG-IP DO will try to fetch configuration from host X.X.X.X, port 443 or 8443, username === admin and password === admin +- ``https://MGMT_IP/mgmt/shared/declarative-onboarding/inspect?targetHost=X.X.X.X&targetPort=443&targetUsername=ZZZ&targetPassword=AAA`` |br| BIG-IP DO will try to fetch configuration from host X.X.X.X, port 443, username === ZZZ and password === AAA Example response from a GET request to the /inspect endpoint: @@ -293,11 +289,11 @@ Example response from a GET request to the /inspect endpoint: * - 408 - Request Timeout - - DO unable to return declaration after 60sec. + - BIG-IP DO unable to return declaration after 60sec. * - 412 - Precondition failed - - DO unable to verify declaration produced by Inspect Handler (/inspect). + - BIG-IP DO unable to verify declaration produced by Inspect Handler (/inspect). * - 400 - Bad Request @@ -305,11 +301,11 @@ Example response from a GET request to the /inspect endpoint: * - 403 - Forbidden - - DO should be executed on BIG-IP or the user should specify target* parameter(s). + - BIG-IP DO should be executed on BIG-IP or the user should specify target* parameter(s). * - 409 - Conflict - - DO cannot provide valid declaration because some of the objects share the same name (for instance VLAN and SelfIp can share **internal** name). Response stills contain declaration which contains INVALID items (suffixed with INVALID_X). See the following example. + - BIG-IP DO cannot provide valid declaration because some of the objects share the same name (for instance VLAN and SelfIp can share **internal** name). Response stills contain declaration which contains INVALID items (suffixed with INVALID_X). See the following example. Example of the response for error 409 diff --git a/docs/images/validate-1.png b/docs/images/validate-1.png index b989aae9..62eb8c1e 100644 Binary files a/docs/images/validate-1.png and b/docs/images/validate-1.png differ diff --git a/docs/images/validate-1a.png b/docs/images/validate-1a.png index 30940cdf..23a72a2d 100644 Binary files a/docs/images/validate-1a.png and b/docs/images/validate-1a.png differ diff --git a/docs/images/validate-2a.png b/docs/images/validate-2a.png index 8de06cd3..6a5d5c34 100644 Binary files a/docs/images/validate-2a.png and b/docs/images/validate-2a.png differ diff --git a/docs/images/validate-3.png b/docs/images/validate-3.png index 9f13058c..30fcb3a6 100644 Binary files a/docs/images/validate-3.png and b/docs/images/validate-3.png differ diff --git a/docs/index.html b/docs/index.html index e940c442..3b335ba8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -24,8 +24,8 @@ @@ -35,4 +35,4 @@ - \ No newline at end of file + diff --git a/docs/index.rst b/docs/index.rst index 33832368..a92c3c8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,44 +1,48 @@ -F5 Declarative Onboarding Documentation -======================================= +F5 BIG-IP Declarative Onboarding Documentation +============================================== -Welcome to the F5 Declarative Onboarding documentation. +Welcome to the F5 BIG-IP Declarative Onboarding documentation. -F5 Declarative onboarding uses a |declare| model to initially configure a BIG-IP device with all of the required settings to get up and running. This includes system settings such as licensing and provisioning, network settings such as VLANs and Self IPs, and clustering settings if you are using more than one BIG-IP system. If you want to use a declarative model to configure applications and services on a BIG-IP device that already has these initial settings, see the |as3| documentation. +This is the documentation for the **latest** version of BIG-IP Declarative Onboarding, if you want to see the documentation for a long term support (LTS) version, use the version selector on the top left (for details, see |supportmd|). -A declarative model means you provide a JSON declaration rather than a set of imperative commands. The declaration represents the configuration which Declarative Onboarding is responsible for creating on a BIG-IP system. You send a declaration file using a single Rest API call. +BIG-IP Declarative onboarding (BIG-IP DO) uses a |declare| model to initially configure a BIG-IP device with all of the required settings to get up and running. This includes system settings such as licensing and provisioning, network settings such as VLANs and Self IPs, and clustering settings if you are using more than one BIG-IP system. If you want to use a declarative model to configure applications and services on a BIG-IP device that already has these initial settings, see the |as3| documentation. -.. NOTE:: The DO RPM, Postman collection, and checksum files can be found on the |release|, as **Assets**. +A declarative model means you provide a JSON declaration rather than a set of imperative commands. The declaration represents the configuration which BIG-IP Declarative Onboarding is responsible for creating on a BIG-IP system. You send a declaration file using a single Rest API call. + +.. IMPORTANT:: Beginning with DO 1.36.0, the default value for **allowService** on a self IP address will be changing from **default** to **none** Until then, DO will present a warning in the response whenever DO receives a declaration that creates or modifies a self IP. + +The DO RPM, Postman collection, and checksum files can be found on the |release|, as **Assets**. You can use Microsoft Visual Studio Code to validate your declarations, see :doc:`validate` for information. -This guide contains information on downloading, installing, and using F5 Declarative Onboarding. +This guide contains information on downloading, installing, and using F5 BIG-IP Declarative Onboarding. -.. NOTE:: To see what's new in Declarative Onboarding, see the the :ref:`revision-history`. + +.. NOTE:: To see what's new in BIG-IP Declarative Onboarding, see the the :ref:`revision-history`. .. _video: -You can also see our Declarative Onboarding overview video: +You can also see our BIG-IP Declarative Onboarding overview video: |vid| To provide feedback on this documentation, you can file a GitHub Issue or email us at solutionsfeedback@f5.com. - -Use the following links, the navigation on the left, and/or the Next and Previous buttons to explore the documentation. - .. toctree:: - :maxdepth: 2 - :includehidden: + :maxdepth: 1 + :hidden: :glob: prereqs faq - components + installation using-do troubleshooting examples - revision-history + apidocs schema-reference + revision-history + .. |declare| raw:: html @@ -49,9 +53,9 @@ Use the following links, the navigation on the left, and/or the Next and Previou
-.. |as3| raw:: html +.. |as3| raw:: htmlq - Application Services 3 (AS3) + Application Services 3 (AS3) .. |vid| raw:: html @@ -61,4 +65,6 @@ Use the following links, the navigation on the left, and/or the Next and Previou GitHub Release +.. |supportmd| raw:: html + Support information on GitHub \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst index be9e9259..42328b9c 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,27 +1,27 @@ .. _installation: -Downloading and installing the Declarative Onboarding package -------------------------------------------------------------- -The Declarative Onboarding package is an RPM file you download, and then upload to the BIG-IP system using the iControl/iApp LX framework. Remember that your BIG-IP must have a management IP address and an **admin** user. +Downloading and installing the BIG-IP Declarative Onboarding package +-------------------------------------------------------------------- +The BIG-IP Declarative Onboarding package is an RPM file you download, and then upload to the BIG-IP system using the iControl/iApp LX framework. Remember that your BIG-IP must have a management IP address and an **admin** user. Downloading the RPM file ~~~~~~~~~~~~~~~~~~~~~~~~ The first task is to download the latest RPM file. Go to the |github|, and download the latest (highest numbered) RPM file. -.. IMPORTANT:: Beginning with DO 1.8.0, the DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in the Declarative Onboarding repository on GitHub. These files can be found on the |release|, as **Assets**. You can find historical files on GitHub by using the **Branch** drop-down, clicking the **Tags** tab, and then selecting the appropriate release. +.. IMPORTANT:: Beginning with BIG-IP DO 1.8.0, the BIG-IP DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in the BIG-IP Declarative Onboarding repository on GitHub. These files can be found on the |release|, as **Assets**. You can find historical files on GitHub by using the **Branch** drop-down, clicking the **Tags** tab, and then selecting the appropriate release. .. TIP:: Once you have downloaded the RPM, we recommend :ref:`hash-ref`. -Uploading and installing the Declarative Onboarding RPM file on the BIG-IP -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Uploading and installing the BIG-IP Declarative Onboarding RPM file on the BIG-IP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After you download the RPM, you must upload and then install it on your BIG-IP system. In this section, we show how to upload the RPM using :ref:`cURL` or :ref:`SCP`. Use only one of the following procedures. .. _14andlater: If using BIG-IP 14.0 or later ````````````````````````````` -If you are using BIG-IP 14.0 or later, the |14| is enforced. As mentioned in the Prerequisites, you must change your **admin** password before attempting to upload or install Declarative Onboarding. +If you are using BIG-IP 14.0 or later, the |14| is enforced. As mentioned in the Prerequisites, you must change your **admin** password before attempting to upload or install BIG-IP Declarative Onboarding. - To change your admin password using the Configuration utility, simply go to the BIG-IP Configuration utility ``https://(IP address of BIG-IP)`` and login using **admin** as the Username and Password. You are forced to change your password. @@ -29,13 +29,13 @@ If you are using BIG-IP 14.0 or later, the |14| is enforced. As mentioned in the .. _uploadscp: -Uploading Declarative Onboarding using SCP -`````````````````````````````````````````` +Uploading BIG-IP Declarative Onboarding using SCP +````````````````````````````````````````````````` -You can use SCP to upload the RPM file to the BIG-IP system. Note that even if you use SCP to upload the RPM file, you still have to use cURL command to install the package. +You can use SCP to upload the RPM file to the BIG-IP system. Even if you use SCP to upload the RPM file, you still have to use cURL command to install the package. #. Open your SCP client, and use the management IP address of your BIG-IP system. -#. Use the **root** account to authenticate to the BIG-IP. The initial root password is **default**. We strongly recommend you change this password after you install Declarative Onboarding (you can change this password using a Declarative Onboarding declaration as shown in :doc:`examples`). If using 14.0 or later, you may be forced to change the password. +#. Use the **root** account to authenticate to the BIG-IP. The initial root password is **default**. We strongly recommend you change this password after you install BIG-IP Declarative Onboarding (you can change this password using a BIG-IP Declarative Onboarding declaration as shown in :doc:`examples`). If using 14.0 or later, you may be forced to change the password. #. Upload the RPM file to the directory **/var/config/rest/downloads**. #. Continue with :ref:`installcurl-ref` @@ -43,10 +43,10 @@ You can use SCP to upload the RPM file to the BIG-IP system. Note that even if .. _uploadcurl: -Uploading Declarative Onboarding using cURL -``````````````````````````````````````````` +Uploading BIG-IP Declarative Onboarding using cURL +`````````````````````````````````````````````````` -If you want to use cURL to install Declarative Onboarding, use the following command syntax. First, set the file name and the BIG-IP credentials, making sure you use the appropriate RPM and build number, and BIG-IP credentials. +If you want to use cURL to install BIG-IP Declarative Onboarding, use the following command syntax. First, set the file name and the BIG-IP credentials, making sure you use the appropriate RPM and build number, and BIG-IP credentials. If you are using a single NIC BIG-IP system, you must include port 8443 after the IP address of the BIG-IP (so the last line in the following would be: IP=IP address of the BIG-IP:8443) @@ -79,8 +79,8 @@ If you are using a Mac, for the first command, use .. _installcurl-ref: -Installing Declarative Onboarding using cURL from the Linux shell -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installing BIG-IP Declarative Onboarding using cURL from the Linux shell +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ No matter which method you used to upload the RPM onto the BIG-IP, you must use the following cURL commands. Copy the following commands to install the package. If you used SCP to upload the package, first set the BIG-IP IP address and credentials as described in :ref:`uploadcurl`. @@ -99,7 +99,7 @@ For information on how you can view the status of installation, see |status|. Checking for a successful installation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After you have uploaded and installed Declarative Onboarding, you can test for a successful installation by using the following methods: +After you have uploaded and installed BIG-IP Declarative Onboarding, you can test for a successful installation by using the following methods: - From your RESTful client, after entering your credentials, use **GET** to send ``https://(IP address of BIG-IP)/mgmt/shared/declarative-onboarding/info`` @@ -131,24 +131,24 @@ In either case, if installation was successful, you should see something similar You can also GET to send ``https://(IP address of BIG-IP)/mgmt/shared/declarative-onboarding/example`` to retrieve an example declaration. -Updating Declarative Onboarding -``````````````````````````````` -When F5 releases a new version of Declarative Onboarding, use the same procedure you used to initially install the RPM. +Updating BIG-IP Declarative Onboarding +`````````````````````````````````````` +When F5 releases a new version of BIG-IP Declarative Onboarding, use the same procedure you used to initially install the RPM. -.. NOTE:: Installing or uninstalling Declarative Onboarding does not affect the BIG-IP configuration created by Declarative Onboarding. +.. NOTE:: Installing or uninstalling BIG-IP Declarative Onboarding does not affect the BIG-IP configuration created by BIG-IP Declarative Onboarding. Reverting to a previous version ``````````````````````````````` -If for any reason you want to revert to a previous version of Declarative Onboarding, you must first remove the version on your BIG-IP system (:guilabel:`iApps > Package Management LX > f5-declarative-onboarding > Uninstall`). After you uninstall, you can import the RPM for the version of Declarative Onboarding you want to use. +If for any reason you want to revert to a previous version of BIG-IP Declarative Onboarding, you must first remove the version on your BIG-IP system (:guilabel:`iApps > Package Management LX > f5-declarative-onboarding > Uninstall`). After you uninstall, you can import the RPM for the version of BIG-IP Declarative Onboarding you want to use. -Viewing the Declarative Onboarding package in the BIG-IP Configuration utility -`````````````````````````````````````````````````````````````````````````````` -If you are using BIG-IP v13.x and want to see the Declarative Onboarding package in the BIG-IP Configuration utility (GUI), from the BIG-IP CLI, you must type the following command: ``touch /var/config/rest/iapps/enable``. You only need to run this command once (per BIG-IP system). This is not necessary with 14.0 and later. +Viewing the BIG-IP Declarative Onboarding package in the BIG-IP Configuration utility +````````````````````````````````````````````````````````````````````````````````````` +If you are using BIG-IP v13.x and want to see the BIG-IP Declarative Onboarding package in the BIG-IP Configuration utility (GUI), from the BIG-IP CLI, you must type the following command: ``touch /var/config/rest/iapps/enable``. You only need to run this command once (per BIG-IP system). This is not necessary with 14.0 and later. -After running that command, you can log into the Configuration utility, and then click **iApps > Package Management LX** and you see the Declarative Onboarding package. If you already had the Configuration utility open, you may need to refresh the page. +After running that command, you can log into the Configuration utility, and then click **iApps > Package Management LX** and you see the BIG-IP Declarative Onboarding package. If you already had the Configuration utility open, you may need to refresh the page. | @@ -156,7 +156,7 @@ After running that command, you can log into the Configuration utility, and then Verifying the integrity of the RPM package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -F5 Networks provides a checksum for each of our Declarative Onboarding releases so you can confirm the integrity of the RPM package. +F5 Networks provides a checksum for each of our BIG-IP Declarative Onboarding releases so you can confirm the integrity of the RPM package. You can get a checksum for a particular template by running one of the following commands, depending on your operating system: @@ -169,7 +169,7 @@ You can compare the checksum produced by that command against the **.sha256** fi .. |github| raw:: html - F5 Declarative Onboarding site on GitHub + F5 BIG-IP Declarative Onboarding site on GitHub .. |status| raw:: html diff --git a/docs/json-pointers.rst b/docs/json-pointers.rst index 318ad492..a9ccadc9 100644 --- a/docs/json-pointers.rst +++ b/docs/json-pointers.rst @@ -1,17 +1,18 @@ +.. _pointers: JSON Pointers ------------- -Declarative Onboarding allows you to use JSON pointers in your declarations to reference other objects. A Declarative Onboarding pointer can identify each node in a declaration. RFC6901 JSON Pointers and RFC Draft Relative JSON Pointers are the basis for Declarative Onboarding pointers, but support special relative references which are meaningful only within Declarative Onboarding declarations. +BIG-IP Declarative Onboarding allows you to use JSON pointers in your declarations to reference other objects. A BIG-IP Declarative Onboarding pointer can identify each node in a declaration. RFC6901 JSON Pointers and RFC Draft Relative JSON Pointers are the basis for BIG-IP Declarative Onboarding pointers, but support special relative references which are meaningful only within BIG-IP Declarative Onboarding declarations. -Declarative Onboarding often uses Declarative Onboarding pointers to refer to objects/properties in declarations. These are analogous to filesystem pathnames so they should be familiar. +BIG-IP Declarative Onboarding often uses BIG-IP Declarative Onboarding pointers to refer to objects/properties in declarations. These are analogous to filesystem pathnames so they should be familiar. -An "absolute" Declarative Onboarding pointer identifying some property in a declaration named item looks like (for example) /T/P/item. +An "absolute" BIG-IP Declarative Onboarding pointer identifying some property in a declaration named item looks like (for example) /T/P/item. -It begins with / (slash) to indicate that it starts from the root of the declaration (which is a JSON object having class=Device). The next token (tokens are the words between the slashes, "T" in the example) is the name of some property in the root object. Most often "T" will be the name of the BIG-IP partition/tenant **/Common**. The exception is when you are using the **DO** class as a wrapper for deploying Declarative Onboarding in a container and using the Credentials pointer. In this case, the pointer would start with /declaration/Credentials. When using this pointer in the main part of the declaration (the Device class), you would not need /declaration, and would only use /Credentials. +It begins with / (slash) to indicate that it starts from the root of the declaration (which is a JSON object having class=Device). The next token (tokens are the words between the slashes, "T" in the example) is the name of some property in the root object. Most often "T" will be the name of the BIG-IP partition/tenant **/Common**. The exception is when you are using the **DO** class as a wrapper for deploying BIG-IP Declarative Onboarding in a container and using the Credentials pointer. In this case, the pointer would start with /declaration/Credentials. When using this pointer in the main part of the declaration (the Device class), you would not need /declaration, and would only use /Credentials. -The next token ("P" in the example) is the name of some property of the object named "T". Most often "P" will be the name of the Declarative Onboarding property, such as failoverGroup. The final token of the pointer names the property of interest ("item" in the example). +The next token ("P" in the example) is the name of some property of the object named "T". Most often "P" will be the name of the BIG-IP Declarative Onboarding property, such as failoverGroup. The final token of the pointer names the property of interest ("item" in the example). -A Declarative Onboarding pointer may have more or fewer than three tokens. You can identify JSON array elements by numbers (because they do not have names); for example, the pointer /Common/failoverGroup/members/0 would refer to the failoverGroup property of the first object in the members array property. +A BIG-IP Declarative Onboarding pointer may have more or fewer than three tokens. You can identify JSON array elements by numbers (because they do not have names); for example, the pointer /Common/failoverGroup/members/0 would refer to the failoverGroup property of the first object in the members array property. To see which properties can use JSON pointers, see the |schema| and look for properties that accept the JSON Pointer which are identified with ``{ "format": "json-pointer" }``. @@ -21,7 +22,7 @@ This section contains examples of how to use these pointers in your declarations Credentials ~~~~~~~~~~~ -In Declarative Onboarding 1.2.0 and later, you can use the **Credentials** pointer to set credentials (or an array of credentials) to use later in your declaration. +In BIG-IP Declarative Onboarding 1.2.0 and later, you can use the **Credentials** pointer to set credentials (or an array of credentials) to use later in your declaration. For example, you could set the credentials for a BIG-IP device using the following example. This creates a numbered array which starts at 0. @@ -45,7 +46,7 @@ And then call the credentials later in the declaration, for example "bigIpUsername": "/Credentials/0/username", "bigIpPassword": "/Credentials/0/password", -You can see a full example of Credentials in action in :ref:`example6`. +You can see a full example of Credentials in action in :ref:`example3`. Referencing other objects in a declaration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -57,7 +58,7 @@ For example, you have the following lines in your declaration. "external-self": { "class": "SelfIp", - "address": "1.2.3.4/24", + "address": "192.0.2.4/24", "vlan": "external", "allowService": "default", "trafficGroup": "traffic-group-1" @@ -83,7 +84,7 @@ For the full clustering example declaration which includes multiple JSON pointer .. |schema| raw:: html - Declarative Onboarding Schema files on Github + BIG-IP Declarative Onboarding Schema files on Github diff --git a/docs/prereqs.rst b/docs/prereqs.rst index b56f6344..a4456f98 100644 --- a/docs/prereqs.rst +++ b/docs/prereqs.rst @@ -4,37 +4,48 @@ Prerequisites and Requirements ------------------------------ -The following are prerequisites for using F5 Declarative Onboarding: +The following are prerequisites for using F5 BIG-IP Declarative Onboarding: -- Domain name resolution is used anywhere the declaration accepts a hostname. DO makes sure that any hostnames are resolvable and fails if they are not. The exception is deviceGroup.members, which do not require hostname resolution as they have been added to the trust. +- BIG-IP Declarative Onboarding does not function properly when the BIG-IP has |appliance| enabled. We strongly recommend disabling Appliance mode when using BIG-IP DO. + +- Domain name resolution is used anywhere the declaration accepts a hostname. BIG-IP DO makes sure that any hostnames are resolvable and fails if they are not. The exception is deviceGroup.members, which do not require hostname resolution as they have been added to the trust. - You must have an existing BIG-IP device with a management IP address. -- The BIG-IP must be running version 13.1.0 or later. - .. IMPORTANT:: Due to changes in TMOS v13.1.1.5, the Declarative Onboarding (DO) Extension is not compatible with this specific TMOS version. Versions before and after 13.1.1.5 are compatible. +- The BIG-IP must be running version 13.1 or later. + +- BIG-IP Declarative Onboarding is not intended to work on BIG-IP versions that have reached End of Life. See `here `_ for more information about BIG-IP versions supported by F5. + .. IMPORTANT:: Due to changes in TMOS v13.1.1.5 and v13.1.3.x, the BIG-IP Declarative Onboarding (BIG-IP DO) Extension is not compatible with this specific TMOS version. Versions before and after 13.1.1.5 are compatible. -- You must have an existing user account with the Administrator role. If you are using 13.1.x, the BIG-IP contains an admin user by default. If you are using 14.x, you **must** reset the admin password before installing Declarative Onboarding. See :ref:`14andlater` for instructions. +- You must have an existing user account with the Administrator role. If you are using 13.1.x, the BIG-IP contains an admin user by default. If you are using 14.x, you **must** reset the admin password before installing BIG-IP Declarative Onboarding. See :ref:`14andlater` for instructions. -- While Declarative onboarding is supported on F5 vCMP systems, network stitching to vCMP Guests or Hosts is not supported. +- While Declarative onboarding is supported on F5 vCMP systems, network stitching to vCMP Guests or Hosts is not supported. Furthermore, creating vCMP guests with a BIG-IP DO declaration is not supported. - If you are using an F5 BYOL license, you must have a valid F5 Networks License Registration Key to include in your declaration. If you do not have one, contact your F5 sales representative. If you do not use a valid F5 license key, your declaration will fail. This is not a requirement if you are using a BIG-IP with pay-as-you-go licensing. - If you are using a single NIC BIG-IP system, you must include port 8443 after the IP address of the BIG-IP in your POST and GET requests, such as ``https://:8443/mgmt/shared/declarative-onboarding`` -- You should be familiar with the F5 BIG-IP and F5 terminology. The settings and features Declarative Onboarding uses are well-documented in the product documentation. For general information and documentation on the BIG-IP system, see the `F5 Knowledge Center `_. +- You should be familiar with the F5 BIG-IP and F5 terminology. The settings and features BIG-IP Declarative Onboarding uses are well-documented in the product documentation. For general information and documentation on the BIG-IP system, see the `F5 Knowledge Center `_. .. _notestips: Notes and tips ~~~~~~~~~~~~~~ -- Beginning with DO 1.8.0, the DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in the Declarative Onboarding repository on GitHub. These files can be found on the |release|, as **Assets**. +.. IMPORTANT:: Beginning with DO 1.35.0, the default value for **allowService** on a self IP address will be changing from **default** to **none** Until then, DO will present a warning in the response whenever DO receives a declaration that creates or modifies a self IP. + +- Beginning with DO 1.34, the task ID is included in the DO log output. BIG-IP DO records error messages in /var/log/restnoded/restnoded.log. + +- Beginning with BIG-IP DO 1.8.0, the BIG-IP DO RPM, Postman collection, and checksum files will no longer be located in the **/dist** directory in the BIG-IP Declarative Onboarding repository on GitHub. These files can be found on the |release|, as **Assets**. + +- Archival of community supported container solution + .. IMPORTANT:: The community-supported solution for BIG-IP DO running in a Docker container is being archived as of BIG-IP DO 1.16. F5 will no longer provide new versions of BIG-IP DO running in a container. -- Declarative Onboarding gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system's phone home feature as described in |phone| +- BIG-IP Declarative Onboarding gathers non-identifiable usage data for the purposes of improving the product as outlined in the end user license agreement for BIG-IP. To opt out of data collection, disable BIG-IP system's phone home feature as described in |phone| -- With the release of Declarative Onboarding 1.2.0, the GitHub repository includes a |github| with all of the example declarations. For information on importing this collection and using Postman collections, see the |postman|. +- With the release of BIG-IP Declarative Onboarding 1.2.0, the GitHub repository includes a |github| with all of the example declarations. For information on importing this collection and using Postman collections, see the |postman|. -- The first time you POST a Declarative Onboarding declaration, the system records the configuration that exists prior to processing the declaration. Declarative Onboarding is meant to initially configure a BIG-IP device. However, if you POST subsequent declarations to the same BIG-IP system, and leave out some of the properties you initially used, the system restores the original properties for those items. **Important**: No matter what you send in a subsequent declaration, Declarative Onboarding will never unlicense a BIG-IP device, it will never delete a user, and it never break the device trust once it has been established. +- The first time you POST a BIG-IP Declarative Onboarding declaration, the system records the configuration that exists prior to processing the declaration. BIG-IP Declarative Onboarding is meant to initially configure a BIG-IP device. However, if you POST subsequent declarations to the same BIG-IP system, and leave out some of the properties you initially used, the system restores the original properties for those items. **Important**: No matter what you send in a subsequent declaration, BIG-IP Declarative Onboarding will never unlicense a BIG-IP device, it will never delete a user, and it never break the device trust once it has been established. Thus, while BIG-IP Declarative Onboarding is declarative, it is not idempotent. - You can use GET to retrieve a sample declaration. Use GET to ``https:///mgmt/shared/declarative-onboarding/example`` @@ -42,14 +53,17 @@ Notes and tips - If you POST a declaration that modifies the password for the admin account, even if the declaration returns an error, the password can be changed. Therefore you may need to update the admin password in the client you are using to send the declaration. -- After using Declarative Onboarding, if you want to use a declarative model to configure applications and services on a BIG-IP device, see the |as3| documentation. - +- After using BIG-IP Declarative Onboarding, if you want to use a declarative model to configure applications and services on a BIG-IP device, see the |as3| documentation. .. |br| raw:: html
+.. |p| raw:: html + + v13.1.1.5 + .. |as3| raw:: html Application Services 3 (AS3) @@ -69,7 +83,7 @@ Notes and tips .. |github| raw:: html - Declarative Onboarding Postman collection + BIG-IP Declarative Onboarding Postman collection .. |phone| raw:: html @@ -77,4 +91,8 @@ Notes and tips .. |release| raw:: html - GitHub Release \ No newline at end of file + GitHub Release + +.. |appliance| raw:: html + + Appliance mode \ No newline at end of file diff --git a/docs/revision-history.rst b/docs/revision-history.rst index 72c91468..8cb9d20e 100644 --- a/docs/revision-history.rst +++ b/docs/revision-history.rst @@ -7,103 +7,210 @@ Document Revision History :widths: 15 100 15 :header-rows: 1 - * - Doc Rev + * - Release - Description - Date - - * - 3.1 - - Updated the documentation for Declarative Onboarding v1.14.0. This release contains the following changes: |br| * Added support for VLAN Failsafe (see :ref:`VLAN Failsafe`) |br| * Added support for creating DNS Resolvers (see :ref:`DNS Resolver`) |br| * Added support for creating a TCP Forward Network Tunnel (see :ref:`Tunnel`) |br| * Added support for Traffic Groups (see :ref:`trafficgroup` and :ref:`Traffic Groups`) |br| |br| Issues Resolved: |br| * Bad class values do not fail schema validation |br| * MAC_Masquerade fails to roll back properly + + * - 1.38 + - Updated the documentation for Declarative Onboarding v1.38.0. This release contains the following changes: |br| * Added support for revoking a license on a BIG-IP, allowing revoking and relicensing in a declaration (see :ref:`Revoke and relicense `) |br| * Added a note to the :ref:`License Class ` section about new behavior when using DO to relicense a BIG-IP device. + - 5-22-23 + + * - 1.37 + - Updated the documentation for Declarative Onboarding v1.37.0. This release contains the following changes: |br| * Added support for configuring Security analytics in a declaration (see :ref:`Security Analytics `) |br| * Added a note to the :ref:`License Class ` section about new behavior when using DO to relicense a BIG-IP device. + - 3-27-23 + + * - 1.36.1 + - Released BIG-IP Declarative Onboarding 1.36.1 as a LTS (Long Term Support) version. See the BIG-IP Declarative Onboarding |supportmd| for information about the BIG-IP Declarative Onboarding support policy. + - 3-9-23 + + * - 1.36 + - Updated the documentation for Declarative Onboarding v1.36.0. This release contains the following changes: |br| * The default value for **allowService** on a **SelfIp** is now **none** (see :ref:`Troubleshooting`) |br| * Updated VXLAN tunnel creation to respect TrafficControl acceptIpOptions values (see the note in :ref:`VXLAN tunnels`) + - 2-9-23 + + * - 1.35 + - Updated the documentation for Declarative Onboarding v1.35.0. This release contains the following changes: |br| * Added the **forceInitialPasswordChange** property for the User class (see the updated :ref:`User class example`) |br| |br| Issues Resolved: |br| * Restarting mcpd may wait for services that are not required, `GitHub Issue 322 `_ |br| * Configuring TACACS can skip reporting errors |br| * Issues when there are no Firewall Policies to be processed |br| * Improve handling on route-domains, by fixing error: "tryuntil error: ioctl failed: No such device", `GitHub Issue 323 `_ + - 1-12-23 + + * - 1.34 + - Updated the documentation for Declarative Onboarding v1.34.0. This release contains the following changes: |br| * Added KexAlgorithms for SSHD (see |sshd| in the Schema Reference) |br| * The task ID is now included in the DO log output (see the note in :ref:`Note and Tips` ) + - 11-15-22 + + * - 1.33 + - Updated the documentation for Declarative Onboarding v1.33.0. This release contains the following changes: |br| * Added a Password Policy class (see :ref:`Password Policy `) |br| * Added a note to self IP stating the default behavior will change in DO 1.35 (see :ref:`Self IP class`) |br| |br| Issues Resolved: |br| * DO issues a warning in the API response when a Self Ip is modified that the default for **allowService** will change to **none** in DO version 1.35.0 |br| Declarations with deviceCertificate via BIG-IQ fail, `GitHub Issue 297 `_ + - 10-4-22 + + * - 1.32 + - Updated the documentation for BIG-IP Declarative Onboarding v1.30.0. This release contains the following changes: |br| * Added support for a GUI security banner in the System class (see the updated :ref:`System example`), `GitHub Issue 316 `_ |br| * Added the ability to enable or disable **snmpd** daemon support of snmpV1 and snmpV2c queries (see the updated :ref:`SNMP example`), `GitHub Issue 316 `_ |br| * DNS_Resolver_forwardZones/name now accept "." as an FQDN, `GitHub Issue 280 `_ |br| |br| Issues Resolved: |br| * RemoteAuthRole console property misconfigured when set to disabled, `GitHub Issue 314 `_ |br| * Fail quicker on bad targetPassphrase value, `GitHub Issue 308 `_ |br| * Fail quicker on bad targetPassphrase value, `GitHub Issue 308 `_ |br| * GSLBGlobals not processed, `GitHub Issue 311 `_ |br| * ManagementRoute Inconsistency, `GitHub Issue 315 `_ + - 8-23-22 + + * - 1.31 + - Updated the documentation for BIG-IP Declarative Onboarding v1.31.0. This release contains the following Issues Resolved: |br| * Improve exception handling when running on BIG-IQ |br| * BIG-IP DO 1.29.0 unable to find /mgmt/tm/sys/provision, `GitHub Issue 306 `_ + - 7-15-22 + + * - 1.30 + - Updated the documentation for BIG-IP Declarative Onboarding v1.30.0. This release contains the following changes: |br| * Added support for validating declarations with either Device or BIG-IP DO class using do.schema.json (see :ref:`Validating a declaration`) |br| |br| Issues Resolved: |br| * Declaration can fail while waiting for unprovisioned service to run |br| * Management firewall policy does not work without AFM module, `GitHub Issue 279 `_ |br| * BIG-IP DO unable to change hostname correctly in Google Cloud, `GitHub Issue 292 `_ + - 5-31-22 + + * - 1.29 + - Updated the documentation for BIG-IP Declarative Onboarding v1.29.0. This release contains the following issues resolved: |br| * SelfIp with RouteDomain cannot reach directly connected network |br| * Licensing can fail if restnoded restarts during processing |br| * SelfIp allowService property does not accept a mix of service:port and default, `GitHub Issue 276 `_ |br| * Security level is not automatically set in the SnmpUser class, `GitHub Issue 282 `_ |br| * Management firewall policy does not work without AFM module, `GitHub Issue 279 `_ + - 4-19-22 + + * - 1.28 + - Updated the documentation for BIG-IP Declarative Onboarding v1.28.0. This release contains the following changes: |br| * Added support for explicitly enabling management DHCP (see :ref:`Management DHCP `) |br| * Added support for specifying route domains in the RoutingBGP and RouteMap classes (see the updated :ref:`BGP example`) |br| |br| Issues Resolved: |br| * Licensing in GCP multi-NIC fails (Upgrade to f5-cloud-libs 4.26.7), `GitHub Issue 248 `_ |br| * URL is incorrect in schema files, `GitHub Issue 285 `_ + - 3-8-22 + + * - 1.27.1 + - Released BIG-IP Declarative Onboarding 1.27.1 as a LTS (Long Term Support) version. See the BIG-IP Declarative Onboarding |supportmd| for information about the BIG-IP Declarative Onboarding support policy. + - 3-8-22 + + * - 1.27 + - Updated the documentation for BIG-IP Declarative Onboarding v1.27.0. This release contains the following resolved issues: |br| * Items containing '.' or '-' characters in their names are not passing schema validation, `GitHub Issue 277 `_ |br| * DNS_Resolver is not idempotent |br| * Tunnel is not idempotent |br| * Cannot update only the description of ManagementIp |br| |br| Issues Resolved: |br| * Several idempotentcy issues are resolved, which required adding defaults for several items in the |system| + - 1-25-22 + + * - 1.26 + - Updated the documentation for BIG-IP Declarative Onboarding v1.26.0. This release contains the following changes: |br| * Added the **remark** field to GSLBDataCenter |br| * Added a new FAQ entry for HTTPD ciphersuite values (see :ref:`HTTPD Ciphersuite`) |br| |br| Issues Resolved: |br| * Declaration fails when Management IP already exists, `GitHub Issue 254 `_ |br| * BIG-IP DO fails when a route with a '/' in the name is added manually between BIG-IP DO runs, `GitHub Issue 267 `_ |br| * Adding a Management Route Resets Management IP to DHCP, `GitHub Issue 269 `_ |br| * Unsupported httpd ciphersuite, `GitHub Issue 178 `_ |br| * Unable to modify SelfIp referenced by ConfigSync, `GitHub Issue 135 `_ |br| * When GTM is enabled, BIG-IP DO returns the error 'Monitor /Common/http is read only' on the second POST even when GSLB is not in the declaration. + - 12-14-21 + + * - 1.25 + - Updated the documentation for BIG-IP Declarative Onboarding v1.25.0. This release contains the following changes: |br| * Added support for VXLAN tunnels (see :ref:`VXLAN tunnels`) |br| * The **timezone** property of the NTP class now uses **UTC** as the default |br| |br| Issues Resolved: |br| * SnmpTrapDestination, SnmpUser, and SnmpCommunity objects cannot be removed once created |br| * Firewall policies managed by AS3 are not ignored, `GitHub Issue 255 `_ |br| * Unable to use remote auth user on BIG-IQ to deploy BIG-IP DO declaration, `GitHub Issue 264 `_ |br| * BIG-IP DO fails when there is pre-existing route configuration with an interface type, `GitHub Issue 265 `_ |br| * BIG-IP DO always enables DHCP on the management interface after POSTing a declaration, `GitHub Issue 261 `_ |br| * Unable to specify gw and target in Route class, `GitHub Issue 274 `_ |br| * BIG-IP DO 1.24.0 doesn't honor Remote Role Groups "remoteAccess": true setting. Was previously working on 1.21.1, `GitHub Issue 268 `_ |br| * RouteDomain example references objects that do not exist, `GitHub Issue 263 `_ + - 11-2-21 + + * - 1.24 + - Updated the documentation for BIG-IP Declarative Onboarding v1.24.0. This release contains the following changes: |br| * Added support for the **ebgpMultihop** property for BGP neighbors (see the updated :ref:`BGP example`) |br| * Added support for **gre** and **geneve** tunnel types (see :ref:`Tunnels`) |br| * Added the optional **chargebackTag** to the BIG-IQ utility examples, and to the :ref:`License class` section (see :ref:`BIG-IQ utility route` and :ref:`BIG-IQ utility no route`) |br| * Added support for firewall rules on the management interface (see :ref:`Firewall rules`) |br| * Added support for network routing access lists (see :ref:`Access Lists`) |br| * Added example declarations for Routes and Management Routes (see :ref:`Routes`) |br| * Added default values for version, port, and network for **SnmpTrapDestination** |br| |br| Issues Resolved: |br| * FirewallPolicy incorrectly allows VLANs to be included in the destination schema object + - 9-21-21 + + * - 1.23 + - Updated the documentation for BIG-IP Declarative Onboarding v1.23.0. This release contains the following changes: |br| * Added support for specifying a static management IP address (see :ref:`Static management IP`) |br| * Added support for preserving DHCP management routes (see :ref:`Preserve DHCP routes`) |br| * Added support for the **dryRun** Controls property to test the declaration without deploying it (see :ref:`dryRun`) |br| * BIG-IP DO now preserves user authorization keys if no keys were provided in declaration, `GitHub Issue 101 `_ |br| |br| Issues Resolved: |br| * Ability to create routes with the Type of Interface, `GitHub Issue 225 `_ |br| * RoutingPrefixList prefixLengthRange does not support strings, `GitHub Issue 237 `_ (see the updated :ref:`Routing Prefix lists`) |br| * Fix FailoverUnicast unicastAddresses.map is not a function |br| * RoutingBGP 'toUpperCase' undefined error, `GitHub Issue 249 `_ + - 8-9-21 + + * - 1.22 + - Updated the documentation for BIG-IP Declarative Onboarding v1.22.0. This release contains the following changes: |br| * Added support for Auto Last Hop on VLANs (see :ref:`Auto Last Hop`) |br| * Properties in the 'traces', 'currentConfig', and 'originalConfig' sections of the response to a request now match what is sent to iControl REST rather than what is in the declaration |br| |br| Issues Resolved: |br| * BIG-IP DO might reboot the BIG-IP system when the same configurations/declaration posted, `GitHub Issue 227 `_ |br| * Match the accepted **hypervisor** list on BIG-IP DO with what is accepted by BIG-IQ, `GitHub Issue 216 `_ |br| * DeviceGroup does not work with IPv6, `GitHub Issue 233 `_ |br| * Race condition when creating self-ip on non-default route-domain, `GitHub Issue 234 `_ |br| * Failover Unicast "cannot read property indexOf of undefined" + - 6-28-21 + + * - 1.21.1 + - Released BIG-IP Declarative Onboarding 1.21.1 as a LTS (Long Term Support) version. See the BIG-IP Declarative Onboarding |supportmd| for information about the BIG-IP Declarative Onboarding support policy. + - 6-23-21 + + * - 1.21 + - Updated the documentation for BIG-IP Declarative Onboarding v1.21.0. This release contains the following changes: |br| * Modified this revision history so the Release column aligns with the BIG-IP DO release |br| * Added support for enabling or disabling LDAP referral chasing (see :ref:`Authentication Methods`) |br| * Dig commands now use +nocookie option to improve compatibility with BIG-IQ 8.0 |br| |br| Issues Resolved: |br| * Invalid config after upgrading BIG-IP DO from 1.15.0, `GitHub Issue 190 `_ |br| * Declaration containing NTP servers by dns name failing in certain cases, `GitHub Issue 125 `_ |br| * Pre-DO GTM Server preventing BIG-IP DO declaration from running, `GitHub Issue 201 `_ |br| * Disk class causes errors on declaration update, `GitHub Issue 177 `_ + - 5-18-21 + + * - 1.20 + - Updated the documentation for BIG-IP Declarative Onboarding v1.20.0. This release contains the following changes: |br| * Added support for BGP Routing (see :ref:`BGP routing`) |br| * Added support for Firewall Policies in a declaration, including Firewall Address and Port lists (`GitHub Issue 198 `_). See :ref:`Firewall Policy` |br| |br| Issues Resolved: |br| * Cannot read property 'applicationData' of undefined, `GitHub Issue 204 `_ |br| * Task status change after restnoded process restarted |br| * Allow DeviceGroup owner to be an IPv6 address without having to use a json-pointer, `Issue 198 `_ |br| * Improve schema compatibility with BIG-IQ UI + - 4-6-21 + + * - 1.19 + - Updated the documentation for BIG-IP Declarative Onboarding v1.19.0. This release contains the following changes: |br| * Added support for GSLB health monitors (see :ref:`GSLB Monitors`) |br| * Added support for GSLB Prober pools (see :ref:`Prober pools`) |br| * Added support for GSLB virtual servers (see the updated :ref:`GSLB Server` example) |br| |br| Issues Resolved: |br| * Improve behavior when tenant is missing, `GitHub Issue 118 `_ + - 2-23-21 + + * - 1.18 + - Updated the documentation for BIG-IP Declarative Onboarding v1.18.0. This release contains the following changes: |br| * Added support for GSLB Data Centers in a declaration (see :ref:`GSLB Data Center`) |br| * Added support for GSLB Servers in a declaration (see :ref:`GSLB Server`) |br| * Added support for routing prefix lists (see :ref:`Prefix list example`) |br| * Added support for using an external auth provider for BIG-IQ licensing (see :ref:`External Auth Provider`) |br| * The version of BIG-IP DO is now displayed in the logs on startup |br| |br| Issues Resolved: |br| * Can only create one DeviceGroup, `GitHub Issue 149 `_ |br| * GSLB schema defaults are not applied in some cases + - 1-12-21 + + * - 1.17 + - Updated the documentation for BIG-IP Declarative Onboarding v1.17.0. This release contains the following changes: |br| * Added support for Failover Multicast (see :ref:`Failover Multicast`) |br| * Updated the :ref:`Auth Methods` example declaration to include the new sslCaCert property (see :ref:`Auth Methods`) |br| * Added support for configuring Global GSLB settings (see :ref:`Global GSLB settings`) |br| * Added support for using variables in some RemoteAuthRole properties (see the :ref:`Remote Auth role variable example`) |br| * Added support for a parent Route Domain (see the updated :ref:`Route Domain` example) |br| * BIG-IP DO now accepts **all** as a single word for HTTPD allow value, `GitHub Issue 163 `_ |br| * Removed the BIG-IP DO in a container page as that community supported solution has been deprecated |br| * Updated the BIG-IQ examples to change the bigIpPassword to match the password being set in the User Class (for example, see :ref:`Licensing with BIG-IQ`) |br| * Added more categories for example declarations (see :doc:`examples`) |br| * Added a note to :doc:`examples` stating all BIG-IP examples will work on BIG-IQ when adding the BIG-IQ section to the declaration |br| * Added notes to the :doc:`do-on-bigiq` page stating **dry-run** is not supported on BIG-IQ, and GET requests are supported |br| |br| Issues Resolved: |br| * RemoteAuthRole remoteAccess property logic is backwards |br| * Disk size must be larger than current size |br| * Unable to specify route domain in route gw address, `GitHub Issue 140 `_ + - 11-20-20 + + * - 1.16 + - Updated the documentation for BIG-IP Declarative Onboarding v1.16.0. This release contains the following changes: |br| * Added support for connection and persistence mirroring using the new MirrorIp class, `GitHub Issue 112 `_ (see :ref:`example29`) |br| * Added an example showing how to add an advisory banner in a declaration (see :ref:`example30`) |br| * Added an example declaration for increasing the memory for restjavad (see :ref:`example31` and :ref:`restjavad`) |br| * Updated the note for vCMP systems on the :doc:`prereqs` page stating that creating vCMP guests with a BIG-IP DO declaration is not supported |br| * Added a note on the :doc:`do-container` and :ref:`Warnings` pages stating that F5 is archiving the community-supported BIG-IP DO in a container solution |br| * Updated the note in :doc:`prereqs` to include BIG-IP 13.1.3.x as incompatible with BIG-IP Declarative Onboarding |br| |br| Issues Resolved: |br| * Retry license install if BIG-IP DO receives a connection reset |br| * Target VLAN errors from the inspect endpoint |br| * Fix minor schema issues: No type for minPathMtu and use const for Tunnel class |br| * Route creation order can be incorrect (`GitHub Issue 147 `_) + - 10-13-20 + + * - 1.15 + - Updated the documentation for BIG-IP Declarative Onboarding v1.15.0. This release contains the following changes: |br| * Added support for allowed source IP addresses for SSHD (see the updated :ref:`SSHD example`) |br| * Added support for the **tenant** property in the License class allowing an optional description of the license (see the *No Route* examples in :doc:`big-iq-licensing` and `bigiq-examples`) |br| * Added support for multiple failover unicast addresses (see :ref:`founi`) |br| * Added support for traces in BIG-IP DO responses (see :ref:`example27`) |br| * Added support for creating routes in the LOCAL_ONLY partition (see :ref:`example28`) |br| * Added more information about the Webhook property in :ref:`base-comps`, and an example of the request sent to the webhook |br| * Updated the support notice for the community-supported :ref:`BIG-IP DO Container` to remove mention of the container being fully supported in the future |br| * Added a troubleshooting entry for a restjavad issue (see :ref:`restjavad`) |br| * Added support for BIG-IP 16.0 |br| |br| Issues Resolved: |br| * Improve schema for use with BIG-IQ 7.1 + - 09-01-20 + + * - 1.14 + - Updated the documentation for BIG-IP Declarative Onboarding v1.14.0. This release contains the following changes: |br| * Added support for VLAN Failsafe (see :ref:`VLAN Failsafe`) |br| * Added support for creating DNS Resolvers (see :ref:`DNS Resolver`) |br| * Added support for creating a TCP Forward Network Tunnel (see :ref:`Tunnel`) |br| * Added support for Traffic Groups (see :ref:`trafficgroup` and :ref:`Traffic Groups`) |br| |br| Issues Resolved: |br| * Bad class values do not fail schema validation |br| * MAC_Masquerade fails to roll back properly - 07-21-20 - * - 3.0 - - Updated the documentation for Declarative Onboarding v1.13.0. This release contains the following changes: |br| * Added support for SSL in LDAP configurations (see the :ref:`authmethods`) |br| * Added support for the userAgent property in the new Controls class (see :ref:`example19`) |br| * Added support for disabling the update auto-check in a declaration - `GitHub Issue 107 `_ (see :ref:`systemex`) |br| * Added support for Audit Logging - `GitHub Issue 120 `_ (see :ref:`example20`) |br| * Added support for Mac Masquerade - `GitHub Issue 96 `_ (see :ref:`example21`) |br| |br| Issues Resolved: |br| * Cannot create a device group with AFM provisioned (`GitHub Issue 138 `_) |br| * Problems with latest Azure image |br| * charset not allowed in Content-Type header (`GitHub Issue 79 `_) + * - 1.13 + - Updated the documentation for BIG-IP Declarative Onboarding v1.13.0. This release contains the following changes: |br| * Added support for SSL in LDAP configurations (see the :ref:`authmethods`) |br| * Added support for the userAgent property in the new Controls class (see :ref:`example19`) |br| * Added support for disabling the update auto-check in a declaration - `GitHub Issue 107 `_ (see :ref:`systemex`) |br| * Added support for Audit Logging - `GitHub Issue 120 `_ (see :ref:`example20`) |br| * Added support for Mac Masquerade - `GitHub Issue 96 `_ (see :ref:`example21`) |br| |br| Issues Resolved: |br| * Cannot create a device group with AFM provisioned (`GitHub Issue 138 `_) |br| * Problems with latest Azure image |br| * charset not allowed in Content-Type header (`GitHub Issue 79 `_) - 06-02-20 - * - 2.9 - - Updated the documentation for Declarative Onboarding v1.12.0. This release contains the following changes: |br| * Added support for updating/uploading Device certificates (see :ref:`example18`) |br| |br| Issues Resolved: |br| * Provisioning fails if module does not exist on box (`GitHub Issue 91 `_) |br| * Call webhook after declaration requiring reboot |br| * Fix allowed schema versions (also fixed in patch release 1.11.1) |br| * Schema is incompatible with golang regexp (`GitHub Issue 132 `_) |br| * Added missing roles for RemoteAuthRole.role enum (`GitHub Issue 81 `_) |br| * Avoid deleting dos-global-dg device group (`GitHub Issue 103 `_) + * - 1.12 + - Updated the documentation for BIG-IP Declarative Onboarding v1.12.0. This release contains the following changes: |br| * Added support for updating/uploading Device certificates (see :ref:`example18`) |br| |br| Issues Resolved: |br| * Provisioning fails if module does not exist on box (`GitHub Issue 91 `_) |br| * Call webhook after declaration requiring reboot |br| * Fix allowed schema versions (also fixed in patch release 1.11.1) |br| * Schema is incompatible with golang regexp (`GitHub Issue 132 `_) |br| * Added missing roles for RemoteAuthRole.role enum (`GitHub Issue 81 `_) |br| * Avoid deleting dos-global-dg device group (`GitHub Issue 103 `_) - 04-21-20 - * - 2.8 - - Updated the documentation for Declarative Onboarding v1.11.0. This release contains the following changes: |br| * Added support for provisioning SSL Orchestrator (SSLO), see :ref:`provision-class` |br| * Added support for using IP addresses for Device Group members and owner (see :ref:`devicegroup` and :ref:`example17`) |br| |br| Issues Resolved: |br| * Route Configuration can conflict with DHCP (`GitHub issue 100 `_) |br| * Setting ConfigSync does not handle device name / hostname mismatch (`GitHub Issue 104 `_) |br| * Attempting to modify ConfigSync on non-existing device - device not resolving properly (`GitHub Issue 113 `_) |br| * Requiring a reboot causes task to never complete |br| * Relicensing BIG-IP can be interrupted by service restart + * - 1.11 + - Updated the documentation for BIG-IP Declarative Onboarding v1.11.0. This release contains the following changes: |br| * Added support for provisioning SSL Orchestrator (SSLO), see :ref:`provision-class` |br| * Added support for using IP addresses for Device Group members and owner (see :ref:`devicegroup` and :ref:`example17`) |br| |br| Issues Resolved: |br| * Route Configuration can conflict with DHCP (`GitHub issue 100 `_) |br| * Setting ConfigSync does not handle device name / hostname mismatch (`GitHub Issue 104 `_) |br| * Attempting to modify ConfigSync on non-existing device - device not resolving properly (`GitHub Issue 113 `_) |br| * Requiring a reboot causes task to never complete |br| * Relicensing BIG-IP can be interrupted by service restart - 03-10-20 - * - 2.7 - - Updated the documentation for Declarative Onboarding v1.10.0. This release contains the following changes: |br| * Added the :ref:`system-class` to the Composing a Standalone declaration page |br| * Added support for disabling autoPhonehome in the System class (see :ref:`system-class`) |br| * Added support for provisioning CGNAT in TMOS version 15.0 and later (see :ref:`provision-class`) |br| |br| Issues Resolved: |br| * On BIG-IP 14 and later, revoke license from BIG-IQ did not work |br| * DO now makes sure config is saved before issuing revoke command |br| * Fixed issue when existing Radius servers were present and none were the primary + * - 1.10 + - Updated the documentation for BIG-IP Declarative Onboarding v1.10.0. This release contains the following changes: |br| * Added the :ref:`system-class` to the Composing a Standalone declaration page |br| * Added support for disabling autoPhonehome in the System class (see :ref:`system-class`) |br| * Added support for provisioning CGNAT in TMOS version 15.0 and later (see :ref:`provision-class`) |br| |br| Issues Resolved: |br| * On BIG-IP 14 and later, revoke license from BIG-IQ did not work |br| * BIG-IP DO now makes sure config is saved before issuing revoke command |br| * Fixed issue when existing Radius servers were present and none were the primary - 01-28-20 - - * - 2.6 - - Updated the documentation for Declarative Onboarding v1.9.0. This release contains the following changes: |br| * Added a new query parameter for GET requests for HTTP status codes (see :ref:`getquery`) |br| * Added a link to the AskF5 article for DO and BIG-IQ compatibility |br| |br| Issues Resolved: |br| * DO was unable to set hostname in AWS environment (`K45728203 `_) |br| * Changes to the network property for ManagementRoute and Route would not actually update the config (`Issue 75 `_) |br| * The /example endpoint was not working. + + * - 1.9 + - Updated the documentation for BIG-IP Declarative Onboarding v1.9.0. This release contains the following changes: |br| * Added a new query parameter for GET requests for HTTP status codes (see :ref:`getquery`) |br| * Added a link to the AskF5 article for BIG-IP DO and BIG-IQ compatibility |br| |br| Issues Resolved: |br| * BIG-IP DO was unable to set hostname in AWS environment (`K45728203 `_) |br| * Changes to the network property for ManagementRoute and Route would not actually update the config (`Issue 75 `_) |br| * The /example endpoint was not working. - 12-03-19 - * - 2.5 - - Updated the documentation for Declarative Onboarding v1.8.0. This release contains the following changes: |br| * Added support for SSHD (see the :ref:`SSHD example`) |br| * Added support for HTTPD (see the :ref:`HTTPD example`) |br| * Added a System class which includes cliInactivityTimeout, consoleInactivityTimeout, and hostname (see :ref:`System example`) |br| * Added a note about DO collecting non-identifiable usage data (see :ref:`notestips`) |br| * Added a troubleshooting entry and other notes about DO performing hostname resolution, and failing if the hostname resolution fails (see :ref:`Troubleshooting`) |br| * Added a troubleshooting entry and other notes about the **/dist** directory going away on GitHub, and the DO RPM being available as a release Asset (see :ref:`Troubleshooting`) |br| |br| Issues Resolved: |br| * DO was unable to use management network for SnmpTrapDestination |br| * DO creates incomplete RADIUS authentication configuration |br| * DO was unable to remove Radius System Auth configuration |br| * DO does not remove secondary Radius server when it is absent in declaration + * - 1.8 + - Updated the documentation for BIG-IP Declarative Onboarding v1.8.0. This release contains the following changes: |br| * Added support for SSHD (see the :ref:`SSHD example`) |br| * Added support for HTTPD (see the :ref:`HTTPD example`) |br| * Added a System class which includes cliInactivityTimeout, consoleInactivityTimeout, and hostname (see :ref:`System example`) |br| * Added a note about BIG-IP DO collecting non-identifiable usage data (see :ref:`notestips`) |br| * Added a troubleshooting entry and other notes about BIG-IP DO performing hostname resolution, and failing if the hostname resolution fails (see :ref:`Troubleshooting`) |br| * Added a troubleshooting entry and other notes about the **/dist** directory going away on GitHub, and the BIG-IP DO RPM being available as a release Asset (see :ref:`Troubleshooting`) |br| |br| Issues Resolved: |br| * BIG-IP DO was unable to use management network for SnmpTrapDestination |br| * BIG-IP DO creates incomplete RADIUS authentication configuration |br| * BIG-IP DO was unable to remove Radius System Auth configuration |br| * BIG-IP DO does not remove secondary Radius server when it is absent in declaration - 10-22-19 - * - 2.4 - - Updated the documentation for Declarative Onboarding v1.7.0. This release contains the following changes: |br| * Added the /inspect endpoint for GET requests to retrieve the current device configuration as a DO declaration (see :ref:`inspect-endpoint`) |br| * Added support for LDAP, RADIUS, and TACACS authentication in a declaration (see the :ref:`Auth method example`) |br| * Added support for Remote Roles in authentication (see the :ref:`Remote Roles example`) |br| * Added support for configuring SNMP (see the :ref:`SNMP example`) |br| * Added support for configuring global Traffic Control properties (see :ref:`Traffic Control example`) |br| * Added support for configuring syslog destinations (see :ref:`syslog destination example`) |br| * Added support for using cmp-hash in the VLAN class (see :ref:`cmp-hash example`) |br| * Added support for DAG Globals (see :ref:`DAG Globals example`) |br| * Added support for the Trunk class (see the |trunkref| in the schema reference) |br| * Added a Schema Reference Appendix |br| * Added a note to :ref:`devicegroup` stating as of DO 1.7.0, **owner** is required. |br| * Improved masking of nested secrets |br| * Improved handling of route domains |br| |br| Issues Resolved: |br| * The values of schemaCurrent and schemaMinium do not always return correct values |br| * Management Route class does not work |br| * DO sets task status to ERROR right away while it is still rolling back |br| * DO unable to create new VLAN(s) when no Route Domain(s) specified in declaration. Now DO will add new VLAN(s) to Route Domain with ID 0 unless otherwise specified. |br| * Device Group **owner** is now required |br| * configsyncIp now allows **none** as valid value |br| * When targetSshKey is used DO now tries bash shell to modify targetUsername password if tmsh shell fails |br| * DO now handles the automatic update of the root password when the admin password changes on BIG-IP version 14.0+. + * - 1.7 + - Updated the documentation for BIG-IP Declarative Onboarding v1.7.0. This release contains the following changes: |br| * Added the /inspect endpoint for GET requests to retrieve the current device configuration as a BIG-IP DO declaration (see :ref:`inspect-endpoint`) |br| * Added support for LDAP, RADIUS, and TACACS authentication in a declaration (see the :ref:`Auth method example`) |br| * Added support for Remote Roles in authentication (see the :ref:`Remote Roles example`) |br| * Added support for configuring SNMP (see the :ref:`SNMP example`) |br| * Added support for configuring global Traffic Control properties (see :ref:`Traffic Control example`) |br| * Added support for configuring syslog destinations (see :ref:`syslog destination example`) |br| * Added support for using cmp-hash in the VLAN class (see :ref:`cmp-hash example`) |br| * Added support for DAG Globals (see :ref:`DAG Globals example`) |br| * Added support for the Trunk class (see the |trunkref| in the schema reference) |br| * Added a Schema Reference Appendix |br| * Added a note to :ref:`devicegroup` stating as of BIG-IP DO 1.7.0, **owner** is required. |br| * Improved masking of nested secrets |br| * Improved handling of route domains |br| |br| Issues Resolved: |br| * The values of schemaCurrent and schemaMinium do not always return correct values |br| * Management Route class does not work |br| * BIG-IP DO sets task status to ERROR right away while it is still rolling back |br| * BIG-IP DO unable to create new VLAN(s) when no Route Domain(s) specified in declaration. Now BIG-IP DO will add new VLAN(s) to Route Domain with ID 0 unless otherwise specified. |br| * Device Group **owner** is now required |br| * configsyncIp now allows **none** as valid value |br| * When targetSshKey is used BIG-IP DO now tries bash shell to modify targetUsername password if tmsh shell fails |br| * BIG-IP DO now handles the automatic update of the root password when the admin password changes on BIG-IP version 14.0+. - 09-10-19 - * - 2.3 + * - Unreleased - This documentation only update contains the following changes: |br| * Added a troubleshooting page with an entry about reposting a declaration with new VLANs, Self IPs, and/or Route Domain (see :ref:`trouble`) |br| * Updated the Route Domain example per GitHub issue |54| (see :ref:`routedomain-class`). - 08-01-19 - - * - 2.2 - - Updated the documentation for Declarative Onboarding v1.6.0. This release contains the following changes: |br| * Added support for creating route domains in a declaration (see :ref:`routedomain-class`) |br| * Added support for specifying a management route (see :ref:`mgmtroute-class`) |br| * Added a note to the **tag** row of the :ref:`vlan-class` table stating if you set the tag in DO, the VLAN defaults the **tagged** parameter to **true**. |br| * Added support for specifying a **webhook** URL for response information (see :ref:`base-comps` for usage). |br| |br| Issues Resolved: |br| * Updated :doc:`big-iq-licensing` and the example declarations to change references to ELA/subscription licensing to *utility* licensing. |br| * Removed targetSshKey when filling in targetPassphrase. |br| + + * - 1.6 + - Updated the documentation for BIG-IP Declarative Onboarding v1.6.0. This release contains the following changes: |br| * Added support for creating route domains in a declaration (see :ref:`routedomain-class`) |br| * Added support for specifying a management route (see :ref:`mgmtroute-class`) |br| * Added a note to the **tag** row of the :ref:`vlan-class` table stating if you set the tag in BIG-IP DO, the VLAN defaults the **tagged** parameter to **true**. |br| * Added support for specifying a **webhook** URL for response information (see :ref:`base-comps` for usage). |br| |br| Issues Resolved: |br| * Updated :doc:`big-iq-licensing` and the example declarations to change references to ELA/subscription licensing to *utility* licensing. |br| * Removed targetSshKey when filling in targetPassphrase. |br| - 07-30-19 - * - 2.1 - - Updated the documentation for Declarative Onboarding v1.5.0. This release contains the following changes: |br| * Support for creating an Analytics profile (see :ref:`Creating an Analytics profile `). |br| * Added support for using Authorized Keys in declarations (see :ref:`Keys example `). |br| * Added a new page for :doc:`clustering-managing-devices` |br| * Added a note to the :doc:`prereqs` stating that due to changes in TMOS v13.1.1.5, the Declarative Onboarding Extension is not compatible with that specific TMOS version. |br| * Added the |schemalink| from previous releases to the GitHub repository |br| * Updated :doc:`validate` to clarify the schema URL to use |br| * Updated the documentation theme and indexes. |br| |br| Issues Resolved: |br| * Declarative Onboarding now disables DHCP for DNS/NTP if DO is configuring them (see the note in :ref:`dns-class` and :ref:`ntp-class`) |br| * License keys no longer appear in the log |br| * Radius server secrets no longer appears in the log |br| * LicensePool now respects custom management access port of the BIG-IP that is being licensed |br| * When a 400 is received from restjavad, DO now tries relicensing |br| * Fixed an issue in which initial clustering failure would prevent clustering from working on subsequent attempts due to using the wrong device name. + * - 1.5 + - Updated the documentation for BIG-IP Declarative Onboarding v1.5.0. This release contains the following changes: |br| * Support for creating an Analytics profile (see :ref:`Creating an Analytics profile `). |br| * Added support for using Authorized Keys in declarations (see :ref:`Keys example `). |br| * Added a new page for :doc:`clustering-managing-devices` |br| * Added a note to the :doc:`prereqs` stating that due to changes in TMOS v13.1.1.5, the BIG-IP Declarative Onboarding Extension is not compatible with that specific TMOS version. |br| * Added the |schemalink| from previous releases to the GitHub repository |br| * Updated :doc:`validate` to clarify the schema URL to use |br| * Updated the documentation theme and indexes. |br| |br| Issues Resolved: |br| * BIG-IP Declarative Onboarding now disables DHCP for DNS/NTP if BIG-IP DO is configuring them (see the note in :ref:`dns-class` and :ref:`ntp-class`) |br| * License keys no longer appear in the log |br| * Radius server secrets no longer appears in the log |br| * LicensePool now respects custom management access port of the BIG-IP that is being licensed |br| * When a 400 is received from restjavad, BIG-IP DO now tries relicensing |br| * Fixed an issue in which initial clustering failure would prevent clustering from working on subsequent attempts due to using the wrong device name. - 06-18-19 - - * - 2.0 - - Documentation only update: Added the :ref:`Declarative Onboarding Overview video