Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

[TT-12648 DX-1578] Docs Operator Migration (API Definition and policy feature list) #5102

Merged
merged 54 commits into from
Sep 5, 2024

Conversation

caroltyk
Copy link
Contributor

@caroltyk caroltyk commented Jul 16, 2024

User description

For internal users - Please add a Jira DX PR ticket to the subject!

DX-1578


Preview Link

API Versioning

API definition features tables

Links added to Tyk Operator auth in the following pages

Tyk Operator Certificates - Gateway to upstream authentication

API (Global features)

For questions relating to API global features see description of this PR that was merged into this PR.

Endpoint level features

For questions relating to endpoint level features refer to the description of this PR that was merged into this PR.

Missing examples? (some of these features are marked as supported in API definition table)

  • context variables - UPDATED
  • custom plugins (go, python, Lua) - UPDATED
  • detailed recording in log browser - UPDATED
  • enforced timeout - EXAMPLE LINKED
  • gRPC plugin bundles? - UPDATED Added in gRPC page to mention example not yet documented
  • plugin bundles? - UPDATED - Added in Custom Plugins page to mention example not yet documented
  • internal API (not exposed by Gateway) - UPDATED
  • Proxy Internal example and explanation of how it differs from internal rewrite - UPDATED
  • URL Rewrite advanced triggers is marked in table as not supported, however the feature is used in internal looping examples - UPDATED

Follow-ups

Description


Screenshots (if appropriate)


Checklist

  • I have added a preview link to the PR description.
  • I have reviewed the suggestions made by our AI (PR Agent) and updated them accordingly (spelling errors, rephrasing, etc.)
  • I have reviewed the guidelines for contributing to this repository.
  • I have read the technical guidelines for contributing to this repository.
  • Make sure you have started your change off our latest master.
  • I labelled the PR

PR Type

Documentation


Description

  • Added comprehensive documentation for configuring client authentication methods in Tyk Operator, including JWT, mTLS, and custom plugins.
  • Introduced internal looping configurations with detailed examples and use cases.
  • Documented GraphQL Federation setup with SubGraph and SuperGraph resources.
  • Provided detailed documentation for ApiDefinition CRD features, including API types, management, and authentication methods.
  • Explained configuration of custom plugins, response header transforms, virtual endpoints, URL rewriters, and request header transforms in Tyk Operator.
  • Added Tyk Operator configuration for upstream mTLS and do-not-track middleware.

Changes walkthrough 📝

Relevant files
Documentation
11 files
client-authentication.md
Add documentation for client authentication configurations in Tyk
Operator

tyk-docs/content/product-stack/tyk-operator/advanced-configurations/client-authentication.md

  • Added comprehensive guide on configuring client authentication
    methods.
  • Included example manifests for various authentication methods.
  • Detailed configuration for JWT, mTLS, Basic Authentication, and custom
    plugins.
  • +392/-0 
    internal-looping.md
    Document internal looping configurations and examples       

    tyk-docs/content/product-stack/tyk-operator/advanced-configurations/internal-looping.md

  • Introduced internal looping configuration for Tyk Operator.
  • Explained URL rewrites, triggers, and proxying to internal APIs.
  • Provided detailed examples and use cases.
  • +339/-0 
    graphql-federation.md
    Add GraphQL Federation documentation for Tyk Operator       

    tyk-docs/content/product-stack/tyk-operator/advanced-configurations/graphql-federation.md

  • Added documentation for GraphQL Federation with Tyk Operator.
  • Explained SubGraph and SuperGraph custom resources.
  • Included example manifests for federation setup.
  • +570/-0 
    api-definition.md
    Document supported features of ApiDefinition CRD                 

    tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md

  • Documented supported features of ApiDefinition CRD.
  • Included tables for API types, management, and authentication methods.
  • Detailed traffic routing and endpoint-level features.
  • +122/-0 
    custom-plugins.md
    Document custom plugin configuration in Tyk Operator         

    tyk-docs/content/product-stack/tyk-operator/advanced-configurations/custom-plugins.md

  • Explained configuration of custom plugins using Tyk Operator.
  • Provided example for JavaScript plugin implementation.
  • Detailed plugin lifecycle phases and configuration parameters.
  • +189/-0 
    response-header-tyk-classic.md
    Add Tyk Operator response header transform documentation 

    tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md

  • Added section for configuring response header transform in Tyk
    Operator.
  • Provided examples for API-level and endpoint-level transforms.
  • Included notes for Tyk Gateway versions.
  • +198/-3 
    virtual-endpoint-tyk-classic.md
    Document virtual endpoint configuration in Tyk Operator   

    tyk-docs/content/product-stack/tyk-gateway/middleware/virtual-endpoint-tyk-classic.md

  • Added section for configuring virtual endpoints in Tyk Operator.
  • Provided example configuration and JavaScript function.
  • Explained error handling and proxy behavior.
  • +97/-1   
    url-rewrite-tyk-classic.md
    Document URL rewriter configuration in Tyk Operator           

    tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md

  • Added section for configuring URL rewriter in Tyk Operator.
  • Provided examples for basic and advanced triggers.
  • Linked to internal looping documentation.
  • +99/-2   
    request-header-tyk-classic.md
    Add Tyk Operator request header transform documentation   

    tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md

  • Added section for configuring request header transform in Tyk
    Operator.
  • Provided examples for API-level and endpoint-level transforms.
  • Explained configuration parameters and usage.
  • +117/-3 
    upstream-mtls.md
    Document upstream mTLS configuration in Tyk Operator         

    tyk-docs/content/basic-config-and-security/security/mutual-tls/upstream-mtls.md

  • Added Tyk Operator configuration for upstream mTLS.
  • Explained usage of upstream_certificate_refs and
    upstream_certificates.
  • Provided example configurations and setup instructions.
  • +119/-8 
    do-not-track-tyk-classic.md
    Document do-not-track middleware configuration in Tyk Operator

    tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-tyk-classic.md

  • Added section for configuring do-not-track middleware in Tyk Operator.
  • Provided examples for API-level and endpoint-level configurations.
  • Explained configuration parameters and effects.
  • +69/-1   
    Additional files (token-limit)
    44 files
    request-size-limit-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md

    ...

    +82/-4   
    response-body-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/response-body-tyk-classic.md

    ...

    +138/-1 
    management-of-api.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/advanced-configurations/management-of-api.md

    ...

    +142/-0 
    versioning.md
    ...                                                                                                           

    tyk-docs/content/getting-started/key-concepts/versioning.md

    ...

    +100/-1 
    endpoint-cache-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md

    ...

    +103/-1 
    quick-start-udg.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-udg.md

    ...

    +162/-0 
    write-grpc-plugin.md
    ...                                                                                                           

    tyk-docs/content/plugins/supported-languages/rich-plugins/grpc/write-grpc-plugin.md

    ...

    +69/-0   
    menu.yaml
    ...                                                                                                           

    tyk-docs/data/menu.yaml

    ...

    +64/-12 
    mock-response-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md

    ...

    +52/-1   
    certificate-pinning.md
    ...                                                                                                           

    tyk-docs/content/security/certificate-pinning.md

    ...

    +88/-1   
    allow-list-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-classic.md

    ...

    +53/-2   
    quick-start-http.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-http.md

    ...

    +106/-0 
    block-list-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-classic.md

    ...

    +56/-1   
    circuit-breaker-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md

    ...

    +50/-2   
    request-body-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/request-body-tyk-classic.md

    ...

    +72/-1   
    auth-plugins.md
    ...                                                                                                           

    tyk-docs/content/plugins/plugin-types/auth-plugins/auth-plugins.md

    ...

    +25/-10 
    enforced-timeout-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md

    ...

    +62/-1   
    quick-start-graphql.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-graphql.md

    ...

    +108/-0 
    validate-request-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md

    ...

    +56/-1   
    request-method-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md

    ...

    +46/-2   
    ignore-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-classic.md

    ...

    +48/-1   
    internal-endpoint-tyk-classic.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic.md

    ...

    +40/-1   
    analytics-plugins.md
    ...                                                                                                           

    tyk-docs/content/plugins/plugin-types/analytics-plugins.md

    ...

    +49/-2   
    cors.md
    ...                                                                                                           

    tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/cors.md

    ...

    +43/-3   
    create-an-api.md
    ...                                                                                                           

    tyk-docs/content/tyk-stack/tyk-operator/create-an-api.md

    ...

    +2/-2     
    custom-analytics.md
    ...                                                                                                           

    tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics.md

    ...

    +28/-0   
    load-balancing.md
    ...                                                                                                           

    tyk-docs/content/planning-for-production/ensure-high-availability/load-balancing.md

    ...

    +30/-1   
    secure-an-api.md
    ...                                                                                                           

    tyk-docs/content/tyk-stack/tyk-operator/secure-an-api.md

    ...

    +4/-8     
    open-keyless.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/authentication-authorization/open-keyless.md

    ...

    +6/-0     
    with-tyk-multi-cloud.md
    ...                                                                                                           

    tyk-docs/content/advanced-configuration/manage-multiple-environments/with-tyk-multi-cloud.md

    ...

    +23/-1   
    rate-limiting.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/control-limit-traffic/rate-limiting.md

    ...

    +22/-0   
    client-mtls.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/mutual-tls/client-mtls.md

    ...

    +3/-1     
    access-an-api.md
    ...                                                                                                           

    tyk-docs/content/tyk-stack/tyk-operator/access-an-api.md

    ...

    +3/-6     
    security-policy.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/reference/security-policy.md

    ...

    +20/-0   
    quick-start-tcp.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-tcp.md

    ...

    +24/-0   
    multiple-auth.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md

    ...

    +5/-1     
    basic-auth.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/authentication-authorization/basic-auth.md

    ...

    +4/-0     
    bearer-tokens.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/authentication-authorization/bearer-tokens.md

    ...

    +4/-0     
    ip-blacklisting.md
    ...                                                                                                           

    tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-blacklisting.md

    ...

    +5/-1     
    ip-whitelisting.md
    ...                                                                                                           

    tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-whitelisting.md

    ...

    +5/-1     
    tyk-operator-multiple-organisations.md
    ...                                                                                                           

    tyk-docs/content/product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations.md

    ...

    +2/-2     
    json-web-tokens.md
    ...                                                                                                           

    tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md

    ...

    +4/-0     
    publish-an-api.md
    ...                                                                                                           

    tyk-docs/content/tyk-stack/tyk-operator/publish-an-api.md

    ...

    +1/-5     
    migration.md
    ...                                                                                                           

    tyk-docs/content/tyk-stack/tyk-operator/migration.md

    ...

    +1/-1     

    💡 PR-Agent usage:
    Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

    Copy link

    netlify bot commented Jul 16, 2024

    PS. Pls add /docs/nightly to the end of url

    Name Link
    🔨 Latest commit 3d5376b
    🔍 Latest deploy log https://app.netlify.com/sites/tyk-docs/deploys/66966ac9d63c0a00089de5c8
    😎 Deploy Preview https://deploy-preview-5102--tyk-docs.netlify.app
    📱 Preview on mobile
    Toggle QR Code...

    QR Code

    Use your smartphone camera to open QR code link.

    To edit notification comments on pull requests, go to your Netlify site configuration.

    Copy link

    netlify bot commented Jul 16, 2024

    PS. Pls add /docs/nightly to the end of url

    Name Link
    🔨 Latest commit 09821b7
    🔍 Latest deploy log https://app.netlify.com/sites/tyk-docs/deploys/66d883b979b2bd00099b8e88
    😎 Deploy Preview https://deploy-preview-5102--tyk-docs.netlify.app
    📱 Preview on mobile
    Toggle QR Code...

    QR Code

    Use your smartphone camera to open QR code link.

    To edit notification comments on pull requests, go to your Netlify site configuration.

    Copy link
    Contributor

    @dcs3spp dcs3spp left a comment

    Choose a reason for hiding this comment

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

    @caroltyk PR looking good to me. I have noticed the PR is in draft status and have performed an initial review with minor suggestions / observations:

    • Expand abbreviation instances for CR and CRD
Add an introduction paragraph that explains the objectives of the quick start and what the user will achieve
    • Summarise what each Quickstart does before the yaml file is included
    • Fix links in Quickstart and supported features table in content file tyk-docs/content/product-stack/tyk-operator/reference/security-policy.md
    • Fix links in tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md

    @dcs3spp dcs3spp changed the title [TT-12648] Migrate API Definition and policy feature list to docs [TT-12648 DX-1538] Migrate API Definition and policy feature list to docs Jul 23, 2024
    caroltyk and others added 8 commits August 23, 2024 12:02
    …from corresponding docs pages (#5174)
    
    * link keyless
    * add client to gateway links
    * fix links
    
    ---------
    
    Co-authored-by: Simon Pears <[email protected]>
    * add gateway upstream auth config
    * fix links
    
    ---------
    
    Co-authored-by: Simon Pears <[email protected]>
    add planned endpoint examples included in Google spreadsheet
    
    ---------
    
    Co-authored-by: Simon Pears <[email protected]>
    Co-authored-by: Burak Sekili <[email protected]>
    Add API level global features provided in Google spreadsheet
    
    ---------
    
    Co-authored-by: Simon Pears <[email protected]>
    Co-authored-by: caroltyk <[email protected]>
    @dcs3spp dcs3spp force-pushed the caroltyk-tyk-operator-2 branch from c9dbcd8 to 2d0fe85 Compare August 23, 2024 11:02
    @dcs3spp dcs3spp changed the title [TT-12648 DX-1538] Migrate API Definition and policy feature list to docs [TT-12648 DX-1578] Migrate API Definition and policy feature list to docs Aug 23, 2024
    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Aug 23, 2024

    @caroltyk I have merged the API global and endpoint level feature examples included in the Google Spreadsheet into this PR. I have added preview links and summary of potential missing examples to this PR description

    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Aug 23, 2024

    @caroltyk commit removes file tyk-docs/content/product-stack/tyk-operator/advanced-configurations/api-versioning.md

    That content file is currently referenced from the API definition table in file tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md

    For the Hugo build and CI checks to succeed the API definition table should be updated to remove the link to the deleted file (api versioning) and we should also setup a redirect to an alternative location if users visit that URL for the removed file.

    Which URL should product-stack/tyk-operator/advanced-configurations/api-versioning redirect to in order to avoid 404 page not found errors?

    @caroltyk
    Copy link
    Contributor Author

    @caroltyk commit removes file tyk-docs/content/product-stack/tyk-operator/advanced-configurations/api-versioning.md

    That content file is currently referenced from the API definition table in file tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md

    For the Hugo build and CI checks to succeed the API definition table should be updated to remove the link to the deleted file (api versioning) and we should also setup a redirect to an alternative location if users visit that URL for the removed file.

    Which URL should product-stack/tyk-operator/advanced-configurations/api-versioning redirect to in order to avoid 404 page not found errors?

    I've fixed the link in last commit.

    caroltyk and others added 5 commits September 4, 2024 13:24
    …e not supported in Tyk Operator and move unsupported and undocumented sections with How It Works
    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Sep 4, 2024

    @caroltyk I have moved the unsupported and undocumented features as subsections of the How it works section

    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Sep 4, 2024

    @komalsukhani if you are ok with the changes and comment response would you be able to approve and I will merge and release

    @dcs3spp dcs3spp merged commit 9c4014b into master Sep 5, 2024
    9 checks passed
    @dcs3spp dcs3spp deleted the caroltyk-tyk-operator-2 branch September 5, 2024 08:03
    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Sep 5, 2024

    /release to release-5.5

    3 similar comments
    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Sep 5, 2024

    /release to release-5.5

    @dcs3spp
    Copy link
    Contributor

    dcs3spp commented Sep 5, 2024

    /release to release-5.5

    @yurisasuke
    Copy link
    Member

    /release to release-5.5

    @letzya letzya changed the title [TT-12648 DX-1578] Migrate API Definition and policy feature list to docs [TT-12648 DX-1578] Docs Operator Migration (API Definition and policy feature list) Sep 5, 2024
    @dcs3spp dcs3spp restored the caroltyk-tyk-operator-2 branch September 5, 2024 10:41
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    4 participants